books/docs/architecture/data-models.md

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

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

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

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

---