# 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}
```

---