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
59 lines
2.5 KiB
Markdown
59 lines
2.5 KiB
Markdown
# SchoolCompare frontend and CMS
|
|
|
|
Next.js App Router with React, TypeScript, CSS Modules, Chart.js, Leaflet and
|
|
Payload CMS. It serves school search, comparisons, rankings, school/place detail
|
|
pages and editorial content across England.
|
|
|
|
Start with the [repository overview](../README.md),
|
|
[architecture](../docs/ARCHITECTURE.md) and [development checks](../docs/DEVELOPMENT.md).
|
|
|
|
## Source map
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `app/(frontend)/` | Public root layout, server pages and FastAPI proxy |
|
|
| `app/(payload)/` | Payload root layout, `/admin` and `/cms-api` |
|
|
| `app/robots.ts`, `app/opengraph-image.tsx`, root icons | Site-wide metadata endpoints |
|
|
| `components/` | Client views and reusable display components |
|
|
| `components/school/` | School detail sections |
|
|
| `lib/api.ts`, `lib/types.ts` | Fetch wrappers and manual school API types |
|
|
| `lib/schoolSections.ts`, `lib/compareLogic.ts` | Presentation decisions and data preparation |
|
|
| `context/`, `hooks/` | Comparison state, suggestion state and responsive behaviour |
|
|
| `collections/`, `blocks/`, `migrations/` | CMS schema and production migrations |
|
|
| `__tests__/` | Jest and React Testing Library tests |
|
|
|
|
Do not introduce a shared `app/layout.tsx`: public pages and Payload have separate
|
|
root layouts. Keep root metadata files outside the route groups.
|
|
|
|
## Data and state
|
|
|
|
Server pages fetch initial data directly from `FASTAPI_URL`. Browser fetches use
|
|
`/api` by default, forwarded by `app/(frontend)/api/[...path]/route.ts`.
|
|
`FASTAPI_URL` must include `/api`. See `.env.example` for CMS and API settings.
|
|
|
|
State uses React hooks/context, URL search parameters and localStorage for the
|
|
comparison basket. SWR is not installed. Maps use dynamic Leaflet wrappers.
|
|
Revalidation intervals are configured in fetch wrappers and pages; they vary by
|
|
resource. Backend reloads do not automatically invalidate every Next.js cache.
|
|
|
|
## Commands
|
|
|
|
```sh
|
|
npm ci
|
|
npm run typecheck
|
|
npm test -- --runInBand
|
|
npm run build
|
|
```
|
|
|
|
`test:watch` and `test:coverage` are also available. There is no `lint` script.
|
|
A running application needs the backend/data environment described in the
|
|
[development guide](../docs/DEVELOPMENT.md).
|
|
|
|
After CMS field or editor changes, run `npm run generate:importmap`. Keep
|
|
`payload-types.ts` generated from the CMS schema rather than editing it by hand.
|
|
The build must work without a database connection; avoid module-scope CMS queries
|
|
and DB-backed `generateStaticParams` functions.
|
|
|
|
See [publishing](docs/PUBLISHING.md) for CMS operations and
|
|
[deployment](../docs/DEPLOY.md) for staging and production promotion.
|