books/docs/prd/technical-assumptions.md

Technical Assumptions

Repository Structure

Monorepo:

The project will use a single Git repository containing both frontend and backend code, organized as follows:

books/
├── frontend/             # React + Vite PWA
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── pages/        # Page components
│   │   ├── hooks/        # Custom React hooks
│   │   ├── services/     # API client, utilities
│   │   ├── assets/       # Images, icons
│   │   └── App.jsx       # Root component
│   ├── public/           # Static assets, PWA manifest
│   ├── index.html
│   ├── vite.config.js
│   ├── package.json
│   └── Dockerfile
├── backend/              # Node.js + Express API
│   ├── src/
│   │   ├── routes/       # API route handlers
│   │   ├── controllers/  # Business logic
│   │   ├── services/     # External integrations (Open Library)
│   │   ├── middleware/   # Auth, validation, error handling
│   │   └── server.js     # Express app entry
│   ├── prisma/           # Prisma schema and migrations
│   │   └── schema.prisma
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml    # Local development orchestration
├── .env.example          # Environment variable template
├── docs/                 # Project documentation
└── README.md

Rationale:

• Monorepo simplifies coordination between frontend and backend changes
• Shared tooling and dependencies easier to manage
• Single repository for deployment to Coolify
• Aligns with AI-assisted development workflow (Claude Code can see full context)

Service Architecture

Monolithic Architecture with Separate Frontend/Backend Containers:

• Frontend Container: React PWA served by Vite production build (static files)
• Backend Container: Node.js + Express REST API
• Database: PostgreSQL container (managed by Coolify)

Communication Flow:

User (Browser)
  ↓ HTTPS
Frontend (PWA)
  ↓ REST API calls
Backend (Express)
  ↓ Prisma ORM
PostgreSQL Database

External: Open Library API (book search)

Rationale:

• Simple, proven architecture for MVP scope
• Easy to deploy and debug with only 3 containers
• No need for microservices complexity at this scale
• Aligns with "simplest thing that works" principle
• Frontend and backend can be developed and deployed independently

Deployment:

• Both containers deployed to single Coolify instance
• Reverse proxy (Caddy/Nginx) handles routing and SSL
• Environment-based configuration (dev, production)

Testing Requirements

Unit + Integration Testing:

Frontend:

• Unit Tests: Component testing with Vitest and React Testing Library
• Coverage Target: >70% for critical business logic (pace calculation, validation)
• Tests Required For:
  • Pace calculation logic
  • Form validation
  • Date manipulation utilities
  • API service layer

Backend:

• Unit Tests: Route handlers and business logic with Jest
• Integration Tests: API endpoints with test database
• Coverage Target: >80% for API routes and core logic
• Tests Required For:
  • All REST API endpoints (CRUD operations)
  • Pace calculation algorithms
  • Open Library API integration (mocked)
  • Database operations (via Prisma)

Manual Testing:

• Mobile device testing (iOS Safari, Android Chrome)
• PWA installation and offline functionality
• Cross-browser compatibility
• Responsive design validation

No E2E Testing in MVP:

• Manual user acceptance testing sufficient for single-user MVP
• E2E framework (Playwright/Cypress) can be added post-MVP if needed

Rationale:

• Balances test coverage with development velocity
• Focuses testing on business-critical logic (pace calculation)
• Manual testing acceptable for UI/UX validation in MVP
• Automated tests provide regression safety for future development

Additional Technical Assumptions and Requests

Frontend Technology Stack:

• React 18+ with functional components and hooks
• Vite for build tooling and dev server
• Tailwind CSS for styling (utility-first, mobile-friendly)
• React Context API for state management (no Redux/Zustand needed)
• Axios or Fetch API for HTTP requests
• vite-plugin-pwa for PWA functionality and service worker
• date-fns for date manipulation (lightweight alternative to Moment.js)

Backend Technology Stack:

• Node.js 20+ LTS
• Express 4.x for REST API
• Prisma as ORM for PostgreSQL
• dotenv for environment configuration
• cors middleware for cross-origin requests
• helmet for security headers
• express-validator for input validation

Database:

• PostgreSQL 15+
• Prisma migrations for schema management
• Connection pooling configured in Prisma

Development Tools:

• Git for version control
• ESLint for code linting
• Prettier for code formatting
• Docker and Docker Compose for local development
• Postman/Insomnia for API testing during development

Environment Variables:

• DATABASE_URL - PostgreSQL connection string
• API_PORT - Backend API port (default: 3000)
• FRONTEND_URL - Frontend URL for CORS configuration
• NODE_ENV - Environment (development, production)
• OPEN_LIBRARY_API_URL - Open Library API base URL

Error Handling and Logging:

• Backend: Centralized error handling middleware
• Frontend: Error boundary components for React error handling
• Logging: Console logging in development, structured logging in production (Winston or Pino)

API Design Conventions:

• RESTful endpoints following standard conventions
• JSON request/response bodies
• HTTP status codes: 200 (success), 201 (created), 400 (bad request), 404 (not found), 500 (server error)
• Consistent error response format: { error: "message", details: {} }

Code Quality:

• Use ESLint + Prettier with shared configuration
• Consistent naming conventions (camelCase for JS, kebab-case for files)
• Component naming: PascalCase for React components
• Meaningful variable and function names
• Comments for complex business logic

Performance Optimization:

• Lazy loading for non-critical components
• Image optimization for book covers (cached from Open Library)
• API response caching where appropriate
• Database query optimization (indexes on frequently queried fields)

---