2026-09-14 23:01:15 +01:00
|
|
|
# SchoolCompare
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
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.
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
## Start here
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
- [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)
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
## Repository map
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
| 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 |
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
## Runtime
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
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.
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
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.
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
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.
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
## Validation
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
```sh
|
|
|
|
|
cd nextjs-app
|
|
|
|
|
npm ci
|
|
|
|
|
npm run typecheck
|
|
|
|
|
npm test -- --runInBand
|
2026-01-06 13:52:00 +00:00
|
|
|
```
|
|
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
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.
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
## Deployment
|
2026-01-06 13:52:00 +00:00
|
|
|
|
2026-09-14 23:01:15 +01:00
|
|
|
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.
|
