TudorandClaude Opus 5
eaf5e5d180
The README still opened on "Primary School Compass", a KS2 tool for Wandsworth and Merton served by FastAPI and vanilla JavaScript with Chart.js. Every layer of that sentence is now wrong: coverage is England-wide across KS2, KS4, all-through and post-16, Next.js owns the public UI, and school data comes from dbt-built `marts.*` rather than CSVs loaded at startup. The setup instructions walked a reader into a virtualenv and a CSV import that cannot build the current schema, so following the docs produced an empty database and a wrong mental model at the same time. Replace the narrative docs with two reference documents that were checked against the code: docs/ARCHITECTURE.md for request flow, data ownership, the backend/frontend module boundaries and the real publication sequence, and docs/DEVELOPMENT.md for the checks that actually run, including the container and CI version skew that makes "just run pytest" misleading. The env examples drifted the same way. ALLOWED_ORIGINS is a JSON array, not a comma-separated list; the frontend needs FASTAPI_URL, DATABASE_URL and PAYLOAD_SECRET, none of which were documented; and RATE_LIMIT_BURST, DEFAULT_PAGE_SIZE and MAX_PAGE_SIZE were presented as tuning controls the routes do not consult. Each is now stated as it behaves. MIGRATION_SUMMARY.md keeps its content but gains a banner, because it reads like setup instructions and is not. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016y2J6bs8gbuSJbH18w7Tan
38 lines
1.9 KiB
Markdown
38 lines
1.9 KiB
Markdown
# SchoolCompare project context
|
|
|
|
## Maintained documentation
|
|
|
|
Read [README.md](README.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and
|
|
[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the current implementation.
|
|
[docs/LEGACY_CODE.md](docs/LEGACY_CODE.md) records obsolete paths and deliberate
|
|
compatibility code. Historical design documents are not current setup instructions.
|
|
|
|
## Architecture constraints
|
|
|
|
- Next.js serves the public UI. FastAPI serves school data from dbt-built `marts.*`.
|
|
The backend does not create school tables or import CSVs at startup.
|
|
- School coverage spans England and multiple phases, not only primary schools in
|
|
Wandsworth and Merton.
|
|
- `/api/*` belongs to the FastAPI proxy. Payload uses `/cms-api` and `/admin`.
|
|
- Payload runs inside Next.js, with its own `payload` schema and persistent media.
|
|
Keep CMS migrations independent of school-data transformations.
|
|
- Public and Payload route groups have separate root layouts. Do not introduce
|
|
`app/layout.tsx`. Keep site-wide metadata files at the `app/` root.
|
|
- Builds must succeed with `DATABASE_URL` unset. Do not call `getCachedPayload()`
|
|
at module scope or add DB-backed `generateStaticParams`.
|
|
- After changing CMS fields/editors, run `npm run generate:importmap` and commit
|
|
the generated import map. See `nextjs-app/docs/PUBLISHING.md`.
|
|
- The backend and pipeline GIAS dictionary copies are generated together; preserve
|
|
their parity. Tests enforce it.
|
|
|
|
## SDLC
|
|
|
|
Follow [docs/DEPLOY.md](docs/DEPLOY.md).
|
|
|
|
- Never push directly to `main`. Use a feature branch and a PR with passing checks.
|
|
- Merges deploy staging only. Production promotion is a separate human decision;
|
|
do not trigger the promotion workflow yourself.
|
|
- Update E2E journeys in the same PR when changing user-facing behaviour.
|
|
- Do not attempt to start a local server to test the application; use unit checks
|
|
and the configured integration environment.
|