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

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

---