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)

---