# 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](PLAN.md).

## Backend — quick start

1. Install dependencies:
   - `cd backend`
   - `npm install`
2. Configure environment variables. Copy the root template and edit:

   ```bash
   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:

   ```bash
   npm run build
   npm run dev
   ```

## Frontend — quick start

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

   ```bash
   cd frontend
   cp .env.example .env
   ```

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

2. Install and run:

   ```bash
   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](docs/backend-api-for-frontend.md)
- [Backend operations](docs/backend.md)
- [Backend agent instruction](docs/agent-backend-instruction.md)
- [Backend sync fix instruction](docs/agent-fix-backend-sync-instruction.md)