# Data Models

## Book Model

**Purpose:** Represents a book that the user is tracking for reading progress and deadline management.

**Key Attributes:**
- `id`: Integer - Unique identifier (auto-increment)
- `title`: String (max 500 chars) - Book title
- `author`: String (max 500 chars, optional) - Book author
- `totalPages`: Integer - Total pages in the book
- `coverUrl`: String (max 1000 chars, optional) - URL to book cover image (from Open Library)
- `deadlineDate`: Date - Date by which user needs to finish the book
- `isPrimary`: Boolean (default: false) - Whether this is the user's primary focus book (for v1.1 multi-book support)
- `status`: String (default: "reading") - Book status: "reading", "finished", "paused"
- `createdAt`: DateTime - When book was added
- `updatedAt`: DateTime - Last update timestamp

### TypeScript Interface

```typescript
interface Book {
  id: number;
  title: string;
  author: string | null;
  totalPages: number;
  coverUrl: string | null;
  deadlineDate: Date;
  isPrimary: boolean;
  status: 'reading' | 'finished' | 'paused';
  createdAt: Date;
  updatedAt: Date;
}
```

### Relationships

- Has many `ReadingLog` entries (one-to-many)
- Cascade delete: When a book is deleted, all associated reading logs are deleted

## ReadingLog Model

**Purpose:** Tracks daily reading progress by recording the current page number for a specific book on a specific date.

**Key Attributes:**
- `id`: Integer - Unique identifier (auto-increment)
- `bookId`: Integer - Foreign key to Book model
- `logDate`: Date - Date of the reading log entry
- `currentPage`: Integer - Page number user reached on this date
- `createdAt`: DateTime - When log was created
- `updatedAt`: DateTime - Last update timestamp

### TypeScript Interface

```typescript
interface ReadingLog {
  id: number;
  bookId: number;
  logDate: Date;
  currentPage: number;
  createdAt: Date;
  updatedAt: Date;
}
```

### Relationships

- Belongs to one `Book` (many-to-one)
- Unique constraint: (bookId, logDate) - Only one log per book per day

## ProgressCalculation Model (Derived)

**Purpose:** Not stored in database - computed on-demand from Book and ReadingLog data to show user's reading pace and status.

**Key Attributes:**
- `bookId`: Integer - Book being tracked
- `currentPage`: Integer - Latest logged page
- `totalPages`: Integer - Total pages in book
- `pagesRemaining`: Integer - Pages left to read
- `deadlineDate`: Date - Finish by date
- `daysRemaining`: Integer - Days until deadline
- `requiredPace`: Float - Pages/day needed to finish on time
- `actualPace`: Float - Pages/day based on 7-day rolling average
- `status`: String - "on-track", "slightly-behind", "behind"
- `lastLoggedDate`: Date - Most recent log date

### TypeScript Interface

```typescript
interface ProgressCalculation {
  bookId: number;
  currentPage: number;
  totalPages: number;
  pagesRemaining: number;
  deadlineDate: Date;
  daysRemaining: number;
  requiredPace: number;  // pages/day
  actualPace: number | null;  // pages/day (null if insufficient data)
  status: 'on-track' | 'slightly-behind' | 'behind';
  lastLoggedDate: Date | null;
}
```

### Relationships

- Derived from `Book` and `ReadingLog` models
- Calculated server-side and returned in API responses

---