feat: scaffold frontend app structure

README.md

@@ -0,0 +1,24 @@
+# Calendar Run
+
+Calendar Run is a races calendar project with a backend API for storing and querying race events.
+
+## Quick Start
+
+1. Install dependencies:
+  - `cd backend`
+  - `npm install`
+2. Configure environment variables in `backend/.env`:
+  - `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
+  - Optional API port: `PORT` (priority) or `API_PORT`
+  - **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. Build and run backend:
+  - `npm run build`
+  - `npm run dev`
+
+By default, the API listens on port `3001` if `PORT` and `API_PORT` are not set.
+
+## Backend And API Docs
+
+- [Backend API for Frontend](docs/backend-api-for-frontend.md)
+- [Backend Agent Instruction](docs/agent-backend-instruction.md)
+- [Backend Sync Fix Instruction](docs/agent-fix-backend-sync-instruction.md)