# High Level Architecture

## Technical Summary

The Book Reading Tracker is a **Progressive Web Application (PWA)** built using a **monolithic architecture** with separate frontend and backend containers. The frontend is a **React 18+ PWA** using **Vite** for build tooling and **Tailwind CSS** for styling, deployed as static files. The backend is a **Node.js Express REST API** using **Prisma ORM** for **PostgreSQL 15+** database access. The system integrates with the **Open Library API** for book metadata search. The entire stack is deployed to **Coolify** as Docker containers with automated SSL via Let's Encrypt. This architecture achieves zero ongoing operational costs while providing a mobile-first, offline-capable reading tracking experience that helps users meet book club deadlines through actionable pace calculations.

## Platform and Infrastructure Choice

After evaluating multiple deployment options, the **self-hosted Coolify platform** was selected based on PRD requirements for zero ongoing costs and full control.

**Platform:** Self-Hosted Coolify

**Key Services:**
- **Web Server:** Nginx/Caddy (via Coolify reverse proxy)
- **Application Runtime:** Docker containers for frontend and backend
- **Database:** PostgreSQL 15+ (managed by Coolify)
- **SSL/TLS:** Automatic Let's Encrypt certificates (via Coolify)
- **Backups:** Automated PostgreSQL backups (via Coolify)
- **Monitoring:** Health check endpoints for uptime monitoring

**Deployment Host and Regions:**
- **Host:** User's existing Coolify instance
- **Regions:** Single region (user-specified)
- **Infrastructure:** Containerized deployment with Docker Compose

**Rationale:**
- ✅ Zero ongoing costs (leverages existing infrastructure)
- ✅ Full privacy and control (no third-party cloud dependencies)
- ✅ Aligns with PRD constraint: "As cheap as possible (already have Coolify)"
- ✅ Automatic SSL, backups, and deployment management
- ✅ No vendor lock-in

**Alternatives Considered:**
- **Vercel + Supabase:** Rejected due to ongoing costs and vendor lock-in
- **AWS Full Stack:** Rejected due to complexity and costs
- **Self-hosted on VPS:** Considered but Coolify provides better DX with same infrastructure

## Repository Structure

**Structure:** Monorepo

**Monorepo Tool:** N/A - Simple directory-based monorepo (no Nx/Turborepo needed for this scale)

**Package Organization:**
- **frontend/**: React PWA application
- **backend/**: Node.js Express API
- **docs/**: Project documentation (PRD, architecture, deployment guides)
- **docker-compose.yml**: Development orchestration
- **No shared packages initially** - Can add if needed for shared TypeScript types in future

**Rationale:**
- Simple monorepo structure sufficient for small project
- Avoids complexity of monorepo tools (Nx, Turborepo) for minimal benefit
- All code in single repository for easy AI-assisted development
- Frontend and backend can share repository while maintaining clear boundaries

## High Level Architecture Diagram

```mermaid
graph TB
    User[User - Mobile Browser]
    CDN[Coolify Reverse Proxy<br/>Nginx/Caddy + SSL]
    FE[Frontend Container<br/>React PWA<br/>Vite Static Build]
    BE[Backend Container<br/>Node.js + Express<br/>REST API]
    DB[(PostgreSQL 15+<br/>Database)]
    OL[Open Library API<br/>External Service]

    User -->|HTTPS| CDN
    CDN -->|Static Files| FE
    CDN -->|API Requests /api/*| BE
    FE -->|REST API Calls| BE
    BE -->|Prisma ORM| DB
    BE -->|Book Search| OL

    style User fill:#e1f5ff
    style FE fill:#90EE90
    style BE fill:#FFB366
    style DB fill:#FF6B6B
    style OL fill:#FFD93D
```

## Architectural Patterns

- **Progressive Web App (PWA):** Frontend served as installable PWA with offline capabilities - _Rationale:_ Mobile-first requirement, no app store hassle, works across platforms

- **Monolithic Backend:** Single Express API server handling all business logic - _Rationale:_ Simplicity for MVP, easy to deploy and debug, sufficient for single-user scale

- **Repository Pattern:** Abstract database access through Prisma ORM - _Rationale:_ Type safety, migration management, testability, future flexibility

- **Component-Based UI:** React functional components with hooks - _Rationale:_ Reusability, maintainability, aligns with modern React best practices

- **REST API:** HTTP-based RESTful endpoints with JSON payloads - _Rationale:_ Simple, well-understood, no GraphQL complexity needed for straightforward CRUD

- **Stateless API:** Backend does not maintain session state - _Rationale:_ Scalability, simplicity (no auth in MVP means no sessions)

- **Cache-First Offline Strategy:** Service worker caches assets and API responses - _Rationale:_ Enables offline logging, improves perceived performance

- **Mobile-First Design:** UI designed for small screens, enhanced for desktop - _Rationale:_ Primary use case is mobile logging, desktop is secondary

---