Greg
fa8acef423
- Initialize Git repository with main branch - Create comprehensive .gitignore for Node.js, React, and environment files - Set up directory structure (frontend/, backend/, docs/) - Create detailed README.md with project overview and setup instructions - Add .env.example with all required environment variables - Configure Prettier for consistent code formatting All acceptance criteria met: ✅ Git repository initialized with appropriate .gitignore ✅ Directory structure matches Technical Assumptions ✅ README.md created with project overview and setup docs ✅ .env.example file with all required environment variables ✅ Prettier config files added for code formatting consistency 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
# 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
|
|
|
|
---
|