Router + Context] BookList[Book List Screen] AddBook[Add Book Screen] BookDetail[Book Detail Screen] Calendar[Calendar Component] LogModal[Log Progress Modal] BooksAPI[Books Service
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 ``` --- ## External APIs ### Open Library API - **Purpose:** Search for books by title, author, or ISBN to populate book metadata - **Documentation:** https://openlibrary.org/dev/docs/api/search - **Base URL(s):** https://openlibrary.org - **Authentication:** None (public API, no API key required) - **Rate Limits:** ~100 requests per 5 minutes (unofficial limit, respect fair use) **Key Endpoints Used:** - `GET /search.json?q={query}` - Search for books by keyword, returns title, author, pages, cover IDs **Cover Images:** - Base URL: `https://covers.openlibrary.org/b/id/{cover_id}-{size}.jpg` - Sizes: S (small), M (medium), L (large) - Example: `https://covers.openlibrary.org/b/id/8233808-M.jpg` **Integration Notes:** - Cache search results for 1 hour to reduce API calls - Implement exponential backoff if rate limited (429 response) - Fallback to manual entry if API unavailable - Extract `number_of_pages_median` or first `number_of_pages` value for total pages - Some books may not have cover images (use placeholder) - Consider Google Books API as backup if Open Library quality is insufficient --- ## Core Workflows ### Add Book Workflow ```mermaid sequenceDiagram actor User participant UI as Add Book Screen participant API as Express API participant OL as Open Library API participant DB as PostgreSQL User->>UI: Enter search query UI->>API: GET /api/books/search?q=query API->>OL: GET /search.json?q=query OL-->>API: Book search results (JSON) API-->>UI: Formatted search results UI->>User: Display book results User->>UI: Select book User->>UI: Set deadline date UI->>API: POST /api/books {title, author, pages, deadline} API->>API: Validate input API->>DB: INSERT INTO books DB-->>API: Created book with ID API-->>UI: 201 Created {book} UI->>User: Navigate to Book List UI->>User: Show success message ``` ### Log Progress Workflow ```mermaid sequenceDiagram actor User participant UI as Log Progress Modal participant API as Express API participant DB as PostgreSQL User->>UI: Tap book card UI->>User: Open modal User->>UI: Enter page number UI->>API: POST /api/books/:id/logs {currentPage, logDate} API->>API: Validate input (page > 0, <= totalPages, >= lastPage) API->>DB: INSERT or UPDATE reading_logs DB-->>API: Created/updated log API-->>UI: 201/200 {log} UI->>UI: Close modal UI->>API: GET /api/books (refresh list) API->>DB: SELECT books with progress calculations DB-->>API: Books with latest logs API-->>UI: Books with updated progress UI->>User: Show updated status (green/yellow/red) ``` ### Calculate Progress Workflow ```mermaid sequenceDiagram participant API as Books Controller participant PS as Pace Service participant DB as Prisma Client API->>DB: Get book by ID DB-->>API: Book {totalPages, deadlineDate} API->>DB: Get latest log for book DB-->>API: ReadingLog {currentPage, logDate} API->>PS: calculateRequiredPace(totalPages, currentPage, deadlineDate) PS->>PS: pagesRemaining = totalPages - currentPage PS->>PS: daysRemaining = deadlineDate - today PS->>PS: requiredPace = pagesRemaining / daysRemaining PS-->>API: requiredPace (number) API->>PS: calculateActualPace(bookId, 7 days) PS->>DB: Get logs from last 7 days DB-->>PS: ReadingLog[] (last 7 days) PS->>PS: actualPace = (latestPage - page7DaysAgo) / 7 PS-->>API: actualPace (number or null) API->>PS: calculateStatus(requiredPace, actualPace) PS->>PS: if actualPace >= requiredPace: "on-track" PS->>PS: else if actualPace >= requiredPace * 0.9: "slightly-behind" PS->>PS: else: "behind" PS-->>API: status (string) API-->>Client: ProgressCalculation {pagesRemaining, daysRemaining, requiredPace, actualPace, status} ``` --- ## Database Schema ### Prisma Schema Definition ```prisma // prisma/schema.prisma generator client { provider = "prisma-client-js" } datasource db { provider = "postgresql" url = env("DATABASE_URL") } model Book { id Int @id @default(autoincrement()) title String @db.VarChar(500) author String? @db.VarChar(500) totalPages Int coverUrl String? @db.VarChar(1000) deadlineDate DateTime @db.Date isPrimary Boolean @default(false) status String @default("reading") @db.VarChar(50) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt readingLogs ReadingLog[] @@index([deadlineDate]) @@index([status]) } model ReadingLog { id Int @id @default(autoincrement()) bookId Int logDate DateTime @db.Date currentPage Int createdAt DateTime @default(now()) updatedAt DateTime @updatedAt book Book @relation(fields: [bookId], references: [id], onDelete: Cascade) @@unique([bookId, logDate]) @@index([bookId]) @@index([logDate]) } ``` ### SQL Schema (Generated) ```sql -- Books table CREATE TABLE "Book" ( "id" SERIAL PRIMARY KEY, "title" VARCHAR(500) NOT NULL, "author" VARCHAR(500), "totalPages" INTEGER NOT NULL, "coverUrl" VARCHAR(1000), "deadlineDate" DATE NOT NULL, "isPrimary" BOOLEAN NOT NULL DEFAULT false, "status" VARCHAR(50) NOT NULL DEFAULT 'reading', "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, "updatedAt" TIMESTAMP NOT NULL ); -- Indexes for Books CREATE INDEX "Book_deadlineDate_idx" ON "Book"("deadlineDate"); CREATE INDEX "Book_status_idx" ON "Book"("status"); -- Reading Logs table CREATE TABLE "ReadingLog" ( "id" SERIAL PRIMARY KEY, "bookId" INTEGER NOT NULL, "logDate" DATE NOT NULL, "currentPage" INTEGER NOT NULL, "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, "updatedAt" TIMESTAMP NOT NULL, CONSTRAINT "ReadingLog_book_fkey" FOREIGN KEY ("bookId") REFERENCES "Book"("id") ON DELETE CASCADE ); -- Unique constraint: one log per book per day CREATE UNIQUE INDEX "ReadingLog_bookId_logDate_key" ON "ReadingLog"("bookId", "logDate"); -- Indexes for ReadingLog CREATE INDEX "ReadingLog_bookId_idx" ON "ReadingLog"("bookId"); CREATE INDEX "ReadingLog_logDate_idx" ON "ReadingLog"("logDate"); ``` **Performance Considerations:** - Indexes on `deadlineDate` and `status` for filtering active books - Composite unique index on `(bookId, logDate)` prevents duplicate logs and optimizes queries - Index on `logDate` for date range queries (7-day rolling average) - Cascade delete ensures orphaned logs don't persist when book is deleted --- ## Frontend Architecture ### Component Architecture #### Component Organization ``` frontend/src/ ├── components/ │ ├── layout/ │ │ ├── Header.jsx │ │ ├── Footer.jsx │ │ └── Layout.jsx │ ├── books/ │ │ ├── BookCard.jsx │ │ ├── BookList.jsx │ │ ├── BookSearchResults.jsx │ │ └── AddBookForm.jsx │ ├── progress/ │ │ ├── LogProgressModal.jsx │ │ ├── ProgressDisplay.jsx │ │ └── StatusIndicator.jsx │ ├── calendar/ │ │ ├── Calendar.jsx │ │ ├── CalendarDay.jsx │ │ └── CalendarLegend.jsx │ └── common/ │ ├── Button.jsx │ ├── Input.jsx │ ├── Modal.jsx │ ├── Loading.jsx │ └── ErrorMessage.jsx ├── pages/ │ ├── Home.jsx │ ├── AddBook.jsx │ ├── BookDetail.jsx │ └── CalendarView.jsx ├── hooks/ │ ├── useBooks.js │ ├── useProgress.js │ └── useLogs.js ├── services/ │ ├── api.js (API client setup) │ ├── booksService.js │ └── logsService.js ├── context/ │ └── AppContext.jsx ├── utils/ │ ├── dateUtils.js │ ├── paceUtils.js │ └── validation.js ├── styles/ │ └── index.css (Tailwind directives) └── App.jsx ``` #### Component Template ```typescript // Example: BookCard.jsx import React from 'react'; import { useNavigate } from 'react-router-dom'; import StatusIndicator from '../progress/StatusIndicator'; import { formatDate } from '../../utils/dateUtils'; /** * BookCard - Displays a single book with progress metrics * @param {Object} book - Book object with progress data * @param {Function} onLogProgress - Handler for log progress action */ function BookCard({ book, onLogProgress }) { const navigate = useNavigate(); const handleCardClick = () => { navigate(`/books/${book.id}`); }; const handleLogClick = (e) => { e.stopPropagation(); // Prevent navigation when clicking log button onLogProgress(book); }; return (
{/* Book cover and title */}
);
}
export default BookCard;
```
### State Management Architecture
#### State Structure
```typescript
// context/AppContext.jsx
import React, { createContext, useContext, useState, useEffect } from 'react';
import { booksService } from '../services/booksService';
const AppContext = createContext();
export function AppProvider({ children }) {
const [books, setBooks] = useState([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
// Fetch books on mount
useEffect(() => {
loadBooks();
}, []);
const loadBooks = async () => {
setLoading(true);
setError(null);
try {
const data = await booksService.getActiveBooks();
setBooks(data.books);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
};
const addBook = async (bookData) => {
const newBook = await booksService.addBook(bookData);
setBooks(prev => [...prev, newBook]);
return newBook;
};
const deleteBook = async (bookId) => {
await booksService.deleteBook(bookId);
setBooks(prev => prev.filter(b => b.id !== bookId));
};
const logProgress = async (bookId, currentPage, logDate) => {
await booksService.logProgress(bookId, currentPage, logDate);
// Refresh books to get updated progress
await loadBooks();
};
const value = {
books,
loading,
error,
loadBooks,
addBook,
deleteBook,
logProgress,
};
return
{book.coverUrl ? (
) : (
{/* Progress metrics */}
No cover
)}
{book.title}
{book.author &&{book.author}
}Due: {formatDate(book.deadlineDate)}
Target: {book.requiredPace.toFixed(1)} pages/day
Your pace: {' '} {book.actualPace ? `${book.actualPace.toFixed(1)} pages/day` : 'No data yet'}
{book.pagesRemaining} pages left, {book.daysRemaining} days