books/docs/prd/epic-1-foundation-core-infrastructure.md

Epic 1: Foundation & Core Infrastructure

Epic Goal: Set up the complete development environment and project infrastructure including Git repository, frontend/backend scaffolding, database schema, Docker configuration, and a health check endpoint to validate the entire stack works end-to-end before building features.

Story 1.1: Project Initialization & Repository Setup

As a developer, I want a properly structured monorepo with frontend and backend directories, so that I have a clean foundation for building the application with all necessary tooling configured.

Acceptance Criteria:

1. Git repository initialized with appropriate .gitignore for Node.js, React, and environment files
2. Directory structure matches Technical Assumptions section (frontend/, backend/, docs/)
3. README.md created with project overview, setup instructions, and tech stack documentation
4. .env.example file created listing all required environment variables
5. Root-level package.json created (if using monorepo workspace tools) or separate package.json files in frontend/ and backend/
6. EditorConfig or Prettier config files added for consistent code formatting

Story 1.2: Frontend Scaffolding with Vite + React

As a developer, I want a Vite + React application scaffold with Tailwind CSS configured, so that I can start building UI components with the chosen tech stack.

Acceptance Criteria:

1. Vite project created in frontend/ directory using npm create vite@latest
2. React 18+ configured as the framework
3. Tailwind CSS installed and configured (tailwind.config.js, postcss.config.js)
4. Base styles imported in main CSS file (@tailwind base; @tailwind components; @tailwind utilities;)
5. Sample component renders successfully showing Tailwind styles work
6. ESLint and Prettier configured for React/JavaScript
7. Development server runs successfully on http://localhost:5173 (or configured port)
8. package.json scripts include: dev, build, preview, lint

Story 1.3: Backend Scaffolding with Node.js + Express

As a developer, I want a Node.js Express API scaffold with basic middleware configured, so that I can start building REST API endpoints.

Acceptance Criteria:

1. Express application created in backend/src/server.js
2. Required dependencies installed: express, cors, helmet, dotenv, express-validator
3. Middleware configured: CORS (allowing frontend origin), Helmet (security headers), JSON body parser
4. Environment configuration loaded via dotenv at startup
5. Server listens on port from environment variable (default: 3000)
6. Basic error handling middleware implemented (catches errors, returns JSON response)
7. Health check endpoint created: GET /api/health returns { status: "ok", timestamp: "..." }
8. package.json scripts include: dev (nodemon for auto-reload), start (production)
9. ESLint configured for Node.js/Express patterns

Story 1.4: Database Schema Definition with Prisma

As a developer, I want a Prisma schema defining Books and ReadingLogs tables, so that I have a clear data model ready for implementation.

Acceptance Criteria:

1. Prisma installed in backend/ directory (npm install prisma @prisma/client)
2. Prisma initialized with PostgreSQL provider (npx prisma init)
3. prisma/schema.prisma file defines the following models:

Books Model:

model Book {
  id           Int      @id @default(autoincrement())
  title        String   @db.VarChar(500)
  author       String?  @db.VarChar(500)
  totalPages   Int
  coverUrl     String?  @db.VarChar(1000)
  deadlineDate DateTime @db.Date
  isPrimary    Boolean  @default(false)
  status       String   @default("reading") @db.VarChar(50)
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  readingLogs  ReadingLog[]

  @@index([deadlineDate])
  @@index([status])
}

ReadingLogs Model:

model ReadingLog {
  id          Int      @id @default(autoincrement())
  bookId      Int
  logDate     DateTime @db.Date
  currentPage Int
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  book        Book     @relation(fields: [bookId], references: [id], onDelete: Cascade)

  @@unique([bookId, logDate])
  @@index([bookId])
  @@index([logDate])
}

4. Schema includes appropriate indexes for performance (bookId, logDate, deadlineDate)
5. Relationship defined: Book has many ReadingLogs (one-to-many)
6. Unique constraint on ReadingLog ensures one entry per book per day

Story 1.5: Database Setup & Initial Migration

As a developer, I want the database schema migrated to a PostgreSQL database, so that the application can persist data.

Acceptance Criteria:

1. DATABASE_URL environment variable configured in .env file
2. Prisma migration created: npx prisma migrate dev --name init
3. Migration successfully creates Book and ReadingLog tables in PostgreSQL
4. Prisma Client generated and can be imported in backend code
5. Database connection verified (Prisma Client can connect successfully)
6. Migration files committed to Git (prisma/migrations/)
7. Instructions in README.md for running migrations in new environments

Story 1.6: Docker Configuration for Local Development

As a developer, I want Docker Compose configuration for running the full stack locally, so that I can develop and test the application in a containerized environment matching production.

Acceptance Criteria:

1. Dockerfile created in frontend/ directory:

   • Multi-stage build (build stage + nginx/serve stage for production)
   • Development stage uses Vite dev server
   • Production stage serves static build files

2. Dockerfile created in backend/ directory:

   • Node.js base image (node:20-alpine or similar)
   • Installs dependencies and runs Prisma generate
   • Exposes API port
   • Runs npm start command

3. docker-compose.yml created in project root defining services:

   • postgres: PostgreSQL 15+ with volume for data persistence
   • backend: Builds from backend/Dockerfile, depends on postgres, exposes API port
   • frontend: Builds from frontend/Dockerfile, exposes dev server port, depends on backend
   • Environment variables configured via .env file

4. docker-compose up successfully starts all three containers

5. Frontend accessible at http://localhost:5173 (or configured port)

6. Backend API accessible at http://localhost:3000/api/health

7. Database accessible on PostgreSQL port with credentials from .env

8. Hot reload works for both frontend and backend in development mode

9. README.md updated with Docker setup and usage instructions

Story 1.7: CI/CD Deployment Configuration for Coolify

As a developer, I want deployment configuration ready for Coolify, so that I can deploy the application to production infrastructure.

Acceptance Criteria:

1. Production docker-compose.yml or Coolify configuration file created
2. Environment variable template documented for Coolify deployment
3. Build and deployment process documented in docs/deployment.md:
   • How to configure Coolify project
   • Required environment variables
   • Database connection setup
   • SSL/HTTPS configuration (handled by Coolify)
   • Health check endpoints for monitoring
4. Production Dockerfiles optimized (multi-stage builds, minimal image size)
5. Database migration strategy documented (how to run migrations on deployment)
6. Backup and restore procedures documented for PostgreSQL

---