books/docs/prd/epic-4-calendar-view-data-visualization.md

Epic 4: Calendar View & Data Visualization

Epic Goal: Provide users with a calendar view showing which days they logged reading progress and marking deadline dates, completing the core MVP feature set and enabling users to visualize their reading habits.

Story 4.1: Get Reading Logs for Calendar API Endpoint

As a user, I want an API endpoint that returns all my logged days for a book, so that the frontend can display them on a calendar.

Acceptance Criteria:

1. API endpoint created: GET /api/books/:bookId/logs
2. Endpoint queries all ReadingLog records for the specified book
3. Returns JSON array of logs:

   {
     "logs": [
       {
         "id": 1,
         "logDate": "2025-12-01",
         "currentPage": 150
       },
       {
         "id": 2,
         "logDate": "2025-11-30",
         "currentPage": 138
       }
     ]
   }
   

4. Logs ordered by logDate descending (most recent first)
5. Returns 404 if book not found
6. Returns 200 with empty array if no logs exist
7. Returns 500 if database query fails
8. Integration test written

Story 4.2: Calendar Component UI (Basic)

As a user, I want a calendar view showing the days I logged reading progress, so that I can visualize my reading consistency.

Acceptance Criteria:

1. Calendar view component created in frontend/src/components/Calendar.jsx
2. Component displays a month view calendar (current month by default)
3. Previous/next month navigation buttons
4. Days with logged reading progress marked with a dot or highlight
5. Current date highlighted distinctly
6. Deadline date marked with a special indicator (🎯 or colored border)
7. Component fetches logs from GET /api/books/:bookId/logs on mount
8. Component fetches book details (for deadline date) from GET /api/books/:bookId
9. Days without logs appear as normal calendar days (no indicator)
10. Calendar is mobile-responsive (readable on small screens)
11. Uses a lightweight calendar library (e.g., react-calendar, or custom-built if simple enough)
12. Loading state shown while fetching data
13. Error state shown if API calls fail

Story 4.3: Calendar Screen Integration

As a user, I want a dedicated calendar screen accessible from navigation, so that I can view my reading activity over time.

Acceptance Criteria:

1. Calendar screen component created in frontend/src/pages/CalendarView.jsx
2. Screen includes:
   • Book selector (if multiple books exist) to choose which book's calendar to view
   • Calendar component showing logged days and deadline for selected book
   • Legend explaining visual indicators (dot = logged, highlighted = deadline, etc.)
3. Default: Shows calendar for primary book (or first book if no primary)
4. Book selector displays as dropdown or horizontal scrollable list with book covers/titles
5. Changing selected book updates calendar display
6. Screen accessible from bottom navigation or menu (if navigation exists)
7. Mobile-responsive layout
8. Back button to return to home screen

Story 4.4: Calendar View on Book Detail Screen

As a user, I want to see the calendar for a specific book on its detail screen, so that I don't have to navigate to a separate calendar view.

Acceptance Criteria:

1. Book detail screen (from Story 3.7) updated to include Calendar component
2. Calendar component rendered below progress metrics section
3. Calendar automatically shows logs for the current book (no book selector needed)
4. Calendar can be collapsed/expanded to save screen space (optional, nice-to-have)
5. Calendar updates when a new log is added for the book
6. Mobile-responsive: Calendar doesn't overwhelm small screens (possibly scrollable)

---