Files

T

john-okeefe d981fdf517 docs(dashboard): update Carousel plan with API endpoint and user preferences

Major architectural improvements:

1. Add generic /api/dashboard/sections JSON endpoint
   - Created internal/handlers/dashboard.go (new file)
   - Created internal/router/dashboard.go (new file)
   - Single source of truth for web UI, mobile apps, plugins
   - Follows existing handler/router pattern

2. Update DashboardService to apply user preferences
   - GetSectionItems() now accepts sectionOrder and hiddenSections
   - filterHiddenSections() removes user's hidden sections
   - reorderSections() applies user's custom order
   - Ensures consistent behavior across all clients

3. Separate concerns properly
   - API handlers in internal/handlers/dashboard.go
   - SSR routes remain in internal/router/frontend.go
   - Both use same DashboardService (single source of truth)

4. Reorganize implementation phases
   - Phase 1-3: Database, service, queries
   - Phase 4-6: Handler, router, frontend routes
   - Phase 7-9: Templates and settings
   - Phase 10-11: TypeScript modules
   - Phase 12-13: Documentation and testing

5. Add documentation
   - docs/developer/api/dashboard.md (API reference)
   - docs/user/dashboard.md (user guide)

6. Bruno tests already exist
   - bruno/dashboard/ has 5 comprehensive test files
   - Three-context testing (no user, user, admin)
   - No additional tests needed

Benefits:
- Uniform dashboard across web, mobile, plugins
- Single source of truth (no duplicate logic)
- User preferences respected by all clients
- Follows established project patterns
- Comprehensive test coverage

Timeline: Updated to reflect 13 phases (19-25 days total with TypeScript)

2026-02-17 22:20:54 -05:00

2.7 KiB

Raw Blame History

Dashboard API

Get Dashboard Sections

Retrieve all dashboard sections for a specific library, including smart sections and user collections.

Endpoint: GET /api/dashboard/sections

Authentication: Required (Bearer token)

Query Parameters

Parameter	Type	Required	Description
library_id	string	Yes	Library UUID to fetch sections for
limit	number	No	Items per section (default: 20, max: 100)

Response

Returns array of sections in user's customized order (respects section_order and hidden_sections preferences).

Section Types:

smart: Auto-generated sections based on reading activity
collection: User-created collections with show_on_dashboard: true

Smart Sections:

ID	Title	Icon	Description
continue-reading	Continue Reading	📖	Books with progress > 0% and < 100%
in-progress	In Progress	📚	Books with progress > 0%
recently-added	Recently Added	🆕	Newest items in library
recently-read	Recently Read	✅	Books with progress = 100%
unread	Not Started	📕	Books with no reading progress

Example Response

{
  "sections": [
    {
      "id": "continue-reading",
      "type": "smart",
      "title": "Continue Reading",
      "icon": "📖",
      "items": [
        {
          "id": "uuid-here",
          "title": "Book Title",
          "author": "Author Name",
          "cover_image_path": "/path/to/cover.jpg"
        }
      ],
      "view_all_url": "/section/continue-reading"
    },
    {
      "id": "collection-uuid",
      "type": "collection",
      "title": "My Favorites",
      "icon": "⭐",
      "items": [],
      "view_all_url": null
    }
  ]
}

User Preferences

The endpoint respects user's dashboard preferences:

section_order: Sections returned in user's custom order
hidden_sections: Hidden sections excluded from response
items_per_section: Default limit from user preferences (overridden by ?limit= query param)

Error Responses

Status	Description
400	Missing library_id
400	Invalid library_id
401	Unauthorized
500	Failed to load sections

2.7 KiB Raw Blame History