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](https://nodejs.org/)
- **Docker & Docker Compose** - [Download](https://www.docker.com/)
- **PostgreSQL 15+** (or use Docker)

## Getting Started

### 1. Clone and Setup

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

```bash
# Install frontend dependencies
cd frontend
npm install
cd ..

# Install backend dependencies
cd backend
npm install
cd ..
```

### 3. Database Setup

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

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

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

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

## Development Workflow

### Running Tests

```bash
# Frontend tests
cd frontend
npm test

# Backend tests
cd backend
npm test
```

### Building for Production

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

# Backend runs directly (no build needed)
```

### Database Migrations

```bash
# 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/)

```bash
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/)

```bash
VITE_API_URL=http://localhost:3000/api
```

### Docker Compose (.env at root)

```bash
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**