books/docs/architecture/components.md

# Components

## Frontend Components

### App Shell

**Responsibility:** Root application component managing routing, global state, and PWA features

**Key Interfaces:**
- React Router for navigation
- React Context providers for global state
- PWA service worker registration

**Dependencies:**
- React Router
- PWA service worker (vite-plugin-pwa)
- API service layer

**Technology Stack:** React 18, React Router 6, React Context API

### Book List Screen

**Responsibility:** Display all active books with progress metrics and status indicators

**Key Interfaces:**
- GET /api/books endpoint
- Navigation to Add Book and Book Detail screens
- Log Progress modal trigger

**Dependencies:**
- BooksService (API client)
- BookCard component
- LogProgressModal component

**Technology Stack:** React, Tailwind CSS, date-fns

### Add Book Screen

**Responsibility:** Search for books via Open Library and add them to reading list with deadline

**Key Interfaces:**
- GET /api/books/search endpoint
- POST /api/books endpoint
- Navigation back to Book List

**Dependencies:**
- BooksService (API client)
- BookSearchResults component
- AddBookForm component

**Technology Stack:** React, Tailwind CSS

### Book Detail Screen

**Responsibility:** Show detailed progress metrics, calendar view, and book management options

**Key Interfaces:**
- GET /api/books/:id/progress endpoint
- GET /api/books/:id/logs endpoint
- DELETE /api/books/:id endpoint

**Dependencies:**
- BooksService (API client)
- Calendar component
- LogProgressModal component

**Technology Stack:** React, Tailwind CSS, date-fns

### Calendar Component

**Responsibility:** Visualize reading logs and deadline dates in month view

**Key Interfaces:**
- Accepts logs array and deadline date as props
- Emits date selection events (for future backfill feature)

**Dependencies:**
- date-fns for date manipulation
- None (can use react-calendar or custom implementation)

**Technology Stack:** React, Tailwind CSS, date-fns

### Log Progress Modal

**Responsibility:** Quick 3-tap workflow to log current page number

**Key Interfaces:**
- POST /api/books/:id/logs endpoint
- Accepts book context as props
- Emits success/cancel events to parent

**Dependencies:**
- BooksService (API client)
- Form validation

**Technology Stack:** React, Tailwind CSS

## Backend Components

### Express Application

**Responsibility:** Main HTTP server handling REST API requests

**Key Interfaces:**
- Exposes REST endpoints at /api/*
- Middleware: CORS, Helmet, JSON parser, error handler
- Health check at /api/health

**Dependencies:**
- Express framework
- Route controllers
- Middleware stack

**Technology Stack:** Node.js 20, Express 4.x

### Books Controller

**Responsibility:** Handle all book-related API endpoints

**Key Interfaces:**
- GET /api/books (list active books)
- POST /api/books (add book)
- GET /api/books/:id (get book)
- DELETE /api/books/:id (delete book)
- GET /api/books/search (search Open Library)
- GET /api/books/:id/progress (get progress)

**Dependencies:**
- Prisma database client
- Open Library service
- Pace calculation service

**Technology Stack:** Express, Prisma, express-validator

### Reading Logs Controller

**Responsibility:** Handle reading log API endpoints

**Key Interfaces:**
- GET /api/books/:id/logs (get logs for book)
- POST /api/books/:id/logs (create/update log)

**Dependencies:**
- Prisma database client
- Input validation

**Technology Stack:** Express, Prisma, express-validator

### Open Library Service

**Responsibility:** Integrate with Open Library API for book search

**Key Interfaces:**
- searchBooks(query): Promise<BookSearchResult[]>
- Caches results in-memory (1 hour TTL)

**Dependencies:**
- Native Fetch API
- In-memory cache (Map)

**Technology Stack:** Node.js native Fetch, Map

### Pace Calculation Service

**Responsibility:** Calculate reading pace metrics from book and log data

**Key Interfaces:**
- calculateRequiredPace(totalPages, currentPage, deadlineDate): number
- calculateActualPace(bookId, days): Promise<number | null>
- calculateStatus(requiredPace, actualPace): string

**Dependencies:**
- Prisma database client
- date-fns

**Technology Stack:** date-fns, Prisma

### Database Client

**Responsibility:** Prisma ORM client for PostgreSQL access

**Key Interfaces:**
- Book model CRUD operations
- ReadingLog model CRUD operations
- Migrations management

**Dependencies:**
- PostgreSQL database
- Prisma schema

**Technology Stack:** Prisma, PostgreSQL 15+

## Component Diagrams

```mermaid
graph TB
    subgraph Frontend["Frontend - React PWA"]
        App[App Shell<br/>Router + Context]
        BookList[Book List Screen]
        AddBook[Add Book Screen]
        BookDetail[Book Detail Screen]
        Calendar[Calendar Component]
        LogModal[Log Progress Modal]
        BooksAPI[Books Service<br/>API Client]
    end

    subgraph Backend["Backend - Express API"]
        ExpressApp[Express Application]
        BooksCtrl[Books Controller]
        LogsCtrl[Reading Logs Controller]
        PaceService[Pace Calculation Service]
        OLService[Open Library Service]
        PrismaClient[Prisma ORM Client]
    end

    subgraph External["External Services"]
        DB[(PostgreSQL Database)]
        OpenLib[Open Library API]
    end

    App --> BookList
    App --> AddBook
    App --> BookDetail
    BookDetail --> Calendar
    BookList --> LogModal
    BookDetail --> LogModal

    BookList --> BooksAPI
    AddBook --> BooksAPI
    BookDetail --> BooksAPI
    LogModal --> BooksAPI

    BooksAPI -->|HTTP| ExpressApp
    ExpressApp --> BooksCtrl
    ExpressApp --> LogsCtrl

    BooksCtrl --> PaceService
    BooksCtrl --> OLService
    BooksCtrl --> PrismaClient
    LogsCtrl --> PrismaClient
    PaceService --> PrismaClient

    OLService -->|HTTP| OpenLib
    PrismaClient -->|SQL| DB

    style Frontend fill:#e1f5ff
    style Backend fill:#ffe1cc
    style External fill:#fff4cc
```

---