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
68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
# SchoolCompare
|
|
|
|
SchoolCompare compares schools across England: primary (KS2), secondary (KS4),
|
|
all-through and post-16 provision, with coverage depending on the source dataset.
|
|
It provides school search, postcode maps, comparisons, rankings, place pages,
|
|
Ofsted information, admissions and destination measures. Editorial content lives
|
|
in a Payload CMS blog.
|
|
|
|
## Start here
|
|
|
|
- [Architecture and data flow](docs/ARCHITECTURE.md)
|
|
- [Development and validation](docs/DEVELOPMENT.md)
|
|
- [Deployment and promotion](docs/DEPLOY.md)
|
|
- [Legacy and unused-code inventory](docs/LEGACY_CODE.md)
|
|
- [Frontend conventions](nextjs-app/README.md)
|
|
- [CMS publishing](nextjs-app/docs/PUBLISHING.md)
|
|
|
|
## Repository map
|
|
|
|
| Path | Responsibility |
|
|
|---|---|
|
|
| `backend/` | FastAPI routes, cached school data, read-only SQLAlchemy mappings, feature flags |
|
|
| `nextjs-app/` | Next.js App Router, React UI, Payload CMS, frontend tests |
|
|
| `pipeline/plugins/extractors/` | Custom Singer taps for GIAS, EES, Ofsted and other datasets |
|
|
| `pipeline/transform/` | dbt staging/intermediate models, marts, seeds and data tests |
|
|
| `pipeline/dags/` | Airflow extraction, transformation and publication workflows |
|
|
| `pipeline/scripts/` | Search indexing, code generation and operational diagnostics |
|
|
| `e2e/` | Playwright journeys against a running environment |
|
|
| `.gitea/workflows/` | PR checks, staging deployment and manual production promotion |
|
|
| `scripts/` | CI review tooling and historical data utilities; see the legacy inventory |
|
|
| `docs/superpowers/`, `mockups/` | Design history and prototypes, not application entry points |
|
|
|
|
## Runtime
|
|
|
|
The public site is **Next.js**, not the FastAPI root page. Browser `/api/*`
|
|
requests pass through a Next.js route handler to FastAPI. Server-rendered pages
|
|
call FastAPI directly using `FASTAPI_URL`, including its `/api` suffix.
|
|
|
|
PostgreSQL/PostGIS stores school data. Meltano/Singer extracts source data;
|
|
dbt builds `marts.*`; FastAPI reads those tables. Typesense serves text search
|
|
and autocomplete. Payload runs inside Next.js and owns a separate `payload`
|
|
database schema and uploaded media.
|
|
|
|
There is **no automatic CSV import or sample dataset on startup**. A working
|
|
school-data environment needs populated marts from the pipeline or an approved
|
|
database snapshot. See [development](docs/DEVELOPMENT.md) before choosing a setup.
|
|
|
|
## Validation
|
|
|
|
```sh
|
|
cd nextjs-app
|
|
npm ci
|
|
npm run typecheck
|
|
npm test -- --runInBand
|
|
```
|
|
|
|
Backend checks, pipeline validation, runtime versions and E2E requirements are
|
|
listed in [DEVELOPMENT.md](docs/DEVELOPMENT.md). No `npm run lint` script is
|
|
currently defined.
|
|
|
|
## Deployment
|
|
|
|
Work on a feature branch and open a PR. Merging to `main` builds images and
|
|
deploys staging. Production promotion is a separate, human-triggered Gitea
|
|
workflow. Use [DEPLOY.md](docs/DEPLOY.md) and the Portainer compose files as the
|
|
operational references. The generic compose examples still reference `:latest`,
|
|
which the current release workflow does not publish.
|