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
1.9 KiB
1.9 KiB
SchoolCompare project context
Maintained documentation
Read README.md, docs/ARCHITECTURE.md and docs/DEVELOPMENT.md for the current implementation. 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-apiand/admin.- Payload runs inside Next.js, with its own
payloadschema 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 theapp/root. - Builds must succeed with
DATABASE_URLunset. Do not callgetCachedPayload()at module scope or add DB-backedgenerateStaticParams. - After changing CMS fields/editors, run
npm run generate:importmapand commit the generated import map. Seenextjs-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.
- 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.