books/README.md

Book Reading Tracker

A Progressive Web Application (PWA) for tracking book reading progress and meeting book club deadlines through actionable pace calculations.

Overview

Book Reading Tracker helps you stay on track with book club deadlines by calculating your required reading pace and comparing it against your actual progress. The app provides clear visual feedback (green/yellow/red status indicators) to help you know if you're on pace to finish on time.

Features

• Open Library Integration: Search for books by title, author, or ISBN
• Deadline-Focused Tracking: Set deadlines and get daily page targets
• Pace Calculation: Compare required pace vs. actual 7-day average
• Visual Status Indicators: Green (on track), Yellow (slightly behind), Red (falling behind)
• Calendar View: Visualize your reading progress over time
• PWA Support: Install on mobile devices, works offline
• Mobile-First Design: Optimized for quick logging on the go

Tech Stack

Frontend

• React 18+ - UI framework with functional components and hooks
• Vite - Fast build tool and dev server
• Tailwind CSS - Utility-first CSS framework for styling
• React Router 6 - Client-side routing
• React Context API - Global state management
• vite-plugin-pwa - PWA support with service worker
• date-fns - Date manipulation library

Backend

• Node.js 20 LTS - JavaScript runtime
• Express 4.x - Web framework for REST API
• Prisma - Type-safe ORM for database access
• PostgreSQL 15+ - Relational database
• express-validator - Input validation middleware
• helmet - Security headers middleware
• cors - Cross-origin resource sharing
• Winston - Structured logging (production)

Development & Deployment

• Docker & Docker Compose - Containerization
• Vitest - Frontend testing framework
• Jest - Backend testing framework
• ESLint & Prettier - Code quality and formatting
• Coolify - Self-hosted deployment platform

Project Structure

books/
├── frontend/           # React PWA application
├── backend/            # Node.js Express API
├── docs/               # Project documentation
│   ├── prd/           # Product Requirements (sharded)
│   └── architecture/  # Technical Architecture (sharded)
├── docker-compose.yml # Local development orchestration
├── .env.example       # Environment variable template
└── README.md          # This file

Prerequisites

• Node.js 20 LTS - Download
• Docker & Docker Compose - Download
• PostgreSQL 15+ (or use Docker)

Getting Started

1. Clone and Setup

# Clone repository (if not already done)
git clone <repo-url>
cd books

# Copy environment variables
cp .env.example .env

# Edit .env with your database credentials

2. Install Dependencies

# Install frontend dependencies
cd frontend
npm install
cd ..

# Install backend dependencies
cd backend
npm install
cd ..

3. Database Setup

# Start PostgreSQL with Docker
docker-compose up -d postgres

# Run Prisma migrations
cd backend
npx prisma migrate dev
cd ..

4. Start Development Servers

Option A: Run services individually

# Terminal 1: Start backend
cd backend
npm run dev
# Runs on http://localhost:3000

# Terminal 2: Start frontend
cd frontend
npm run dev
# Runs on http://localhost:5173

Option B: Run all services with Docker

# Start all services (postgres, backend, frontend)
docker-compose up

# Frontend: http://localhost:5173
# Backend: http://localhost:3000/api/health

Development Workflow

Running Tests

# Frontend tests
cd frontend
npm test

# Backend tests
cd backend
npm test

Building for Production

# Build frontend
cd frontend
npm run build
# Output: frontend/dist

# Backend runs directly (no build needed)

Database Migrations

# Create a new migration
cd backend
npx prisma migrate dev --name <migration-name>

# Apply migrations to production
npx prisma migrate deploy

# Open Prisma Studio (database GUI)
npx prisma studio

Environment Variables

Backend (.env in backend/)

DATABASE_URL="postgresql://user:password@localhost:5432/books"
API_PORT=3000
NODE_ENV=development
OPEN_LIBRARY_API_URL=https://openlibrary.org
CORS_ORIGIN=http://localhost:5173

Frontend (.env.local in frontend/)

VITE_API_URL=http://localhost:3000/api

Docker Compose (.env at root)

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=books

API Documentation

The backend API follows RESTful conventions. Full OpenAPI 3.0 specification is available in docs/architecture/api-specification.md.

Health Check: GET /api/health

Key Endpoints:

• GET /api/books - List active books with progress
• POST /api/books - Add a new book
• GET /api/books/:id/progress - Get book progress
• POST /api/books/:id/logs - Log reading progress
• GET /api/books/search?q=query - Search Open Library

Project Documentation

• Product Requirements: docs/prd/index.md
• Technical Architecture: docs/architecture/index.md
• Project Brief: docs/brief.md
• Deployment Guide: docs/deployment.md (coming soon)

Deployment

This application is designed to be deployed on Coolify (self-hosted PaaS). Deployment configuration and instructions will be added in Epic 1, Story 1.7.

Contributing

This is a personal project, but feedback and suggestions are welcome!

License

MIT

---

Built with ❤️ and Claude Code