a2dcf67396
Some checks failed
CI / build-and-test (pull_request) Has been cancelled
- Add PLAN.md and sync backend docs, .env.example, API doc (404 details) - Document mock DB and PORT/API_PORT in docs/backend.md; README monorepo + frontend/.env.example - Migration 002: finish_place column, status registered; mapper and mock DB updated - Frontend: registered status, finishPlace, calendar year/month filters, pace sparkline - Extract createApp for tests; supertest + tsx; GitHub Actions CI Made-with: Cursor
57 lines
1.8 KiB
Markdown
57 lines
1.8 KiB
Markdown
# 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)
|