Calendar Run

Calendar Run is a races calendar project: a backend API (Express + PostgreSQL) and a React SPA for viewing and analyzing your race schedule.

Product scope and data model: PLAN.md.

Backend — quick start

1. Install dependencies:

   • cd backend
   • npm install

2. Configure environment variables. Copy the root template and edit:

   cp .env.example .env
   

   Use the repository root .env (the backend loads it via backend/src/config.ts).

   • DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD — required unless mock mode is on.
   • API port: PORT (takes precedence) or API_PORT (default 3001).
   • No PostgreSQL (CI / local smoke): set CALENDAR_RUN_MOCK_DB=1 (or true). Real DB_* values are not required; the API uses in-memory stubs for SQL used by the HTTP routes. Do not use mock mode for npm run db:migrate or npm run seed.

3. With a real database: from repo root, docker-compose up -d, then cd backend && npm run db:migrate && npm run seed.

4. Build and run API:

   npm run build
   npm run dev
   

Frontend — quick start

1. Configure the API URL for Vite (file is read from frontend/):

   cd frontend
   cp .env.example .env
   

   Edit VITE_API_BASE_URL if the API is not on http://localhost:3001.

2. Install and run:

   npm install
   npm run dev
   

   Default app URL: http://localhost:5173. The backend CORS_ORIGIN must match this origin (see root .env.example).

Docs

• Backend API for Frontend
• Backend operations
• Backend agent instruction
• Backend sync fix instruction