books/docs/architecture/high-level-architecture.md

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

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

---