# c-wilkinson/school-finder architecture

> Architecture diagram of the GitHub repository c-wilkinson/school-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/c-wilkinson/school-finder
- Repository: https://github.com/c-wilkinson/school-finder

## Overview

School Finder turns official English-school datasets into local Parquet data, then lets parents search by postcode, filter and rank schools, compare results, and save personal notes or shortlist decisions. The main runtime path is dataset build → reusable search services → CLI or Streamlit. The graph also includes historical data, benchmarks, subjects, school-detail presentation, and browser persistence. Source-adapter and some UI internals are represented at directory level where their implementation was not excerpted; edges reflect README statements or indexed references, not an inspection of unsampled code.

Main entry points: [`src/school_finder/ui/streamlit_app.py`](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/streamlit_app.py) (Streamlit app), [`src/school_finder/services/search.py`](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/search.py) (Search service), [`src/school_finder/data/parquet.py`](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/parquet.py) (Parquet datasets), [`src/school_finder/data/build.py`](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/build.py) (Dataset builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data ingestion"]
  node_builder["Dataset builder<br/>[build.py]"]
  node_adapters["Source adapters"]
  node_parquet[("Parquet datasets<br/>[parquet.py]")]
  node_manifest["Build manifest<br/>[manifest.py]"]
  node_historydata["Historical data<br/>[history.py]"]
end

subgraph group_core["Search and scoring"]
  node_request["Search request<br/>[search.py]"]
  node_filters["Hard filters<br/>[filters.py]"]
  node_preferences["Preference models<br/>[preferences.py]"]
  node_schoolmodel["School models<br/>[school.py]"]
  node_search["Search service<br/>[search.py]"]
  node_postcode["Postcode lookup<br/>[postcode.py]"]
  node_scoring["Preference scoring<br/>[scoring.py]"]
  node_benchmarks["Benchmarks<br/>[benchmarks.py]"]
  node_subjects["Subject data<br/>[subjects.py]"]
  node_historyservice["History service<br/>[history.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_streamlit["Streamlit app<br/>[streamlit_app.py]"]
  node_detail["School details<br/>[detail.py]"]
  node_comparison["School comparison<br/>[comparison.py]"]
  node_match["Match display<br/>[match.py]"]
  node_formatting["Result formatting<br/>[formatting.py]"]
  node_controls["Search controls<br/>[controls.py]"]
end

subgraph group_personal["Personalisation"]
  node_sessionstate["Session state<br/>[state.py]"]
  node_personalmodel["Personal school state<br/>[personalisation.py]"]
  node_persist["Browser persistence"]
end

node_public[("Public datasets")]
node_browser[("Browser storage")]

node_public -->|"provides data"| node_adapters
node_builder -->|"loads sources"| node_adapters
node_builder -->|"writes datasets"| node_parquet
node_builder -->|"records build"| node_manifest
node_builder -->|"uses history"| node_historydata
node_parquet -->|"stores locally"| node_public
node_cli -->|"runs build"| node_builder
node_cli -->|"runs lookup"| node_search
node_request -->|"defines filters"| node_filters
node_request -->|"accepts priorities"| node_preferences
node_search -->|"reads datasets"| node_parquet
node_search -->|"accepts request"| node_request
node_search -->|"resolves postcode"| node_postcode
node_search -->|"scores results"| node_scoring
node_search -->|"loads benchmarks"| node_benchmarks
node_search -->|"builds results"| node_schoolmodel
node_benchmarks -->|"reads data"| node_parquet
node_historyservice -->|"reads history"| node_historydata
node_historyservice -->|"reads datasets"| node_parquet
node_subjects -->|"reads datasets"| node_parquet
node_streamlit -->|"runs search"| node_search
node_streamlit -->|"requests history"| node_historyservice
node_streamlit -->|"requests subjects"| node_subjects
node_streamlit -->|"renders controls"| node_controls
node_streamlit -->|"renders details"| node_detail
node_streamlit -->|"renders comparison"| node_comparison
node_streamlit -->|"renders matches"| node_match
node_detail -->|"uses formatting"| node_formatting
node_comparison -->|"uses formatting"| node_formatting
node_match -->|"uses formatting"| node_formatting
node_streamlit -->|"manages state"| node_sessionstate
node_sessionstate -->|"stores preferences"| node_personalmodel
node_streamlit -->|"syncs personalisation"| node_persist
node_persist -->|"encodes state"| node_personalmodel
node_persist -->|"persists locally"| node_browser

click node_builder "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/build.py"
click node_adapters "https://github.com/c-wilkinson/school-finder/tree/main/src/school_finder/data/sources"
click node_parquet "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/parquet.py"
click node_manifest "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/manifest.py"
click node_historydata "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/history.py"
click node_request "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/search.py"
click node_filters "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/filters.py"
click node_preferences "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/preferences.py"
click node_schoolmodel "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/school.py"
click node_search "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/search.py"
click node_postcode "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/postcode.py"
click node_scoring "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/scoring.py"
click node_benchmarks "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/benchmarks.py"
click node_subjects "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/subjects.py"
click node_historyservice "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/history.py"
click node_cli "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/cli.py"
click node_streamlit "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/streamlit_app.py"
click node_detail "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/detail.py"
click node_comparison "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/comparison.py"
click node_match "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/match.py"
click node_formatting "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/formatting.py"
click node_controls "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/controls.py"
click node_sessionstate "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/state.py"
click node_personalmodel "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/personalisation.py"
click node_persist "https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/personalisation_storage.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_builder,node_adapters,node_parquet,node_manifest,node_historydata toneBlue
class node_request,node_filters,node_preferences,node_schoolmodel,node_search,node_postcode,node_scoring,node_benchmarks,node_subjects,node_historyservice,node_public,node_browser toneAmber
class node_cli,node_streamlit,node_detail,node_comparison,node_match,node_formatting,node_controls toneMint
class node_sessionstate,node_personalmodel,node_persist toneRose
```

## Components

### Data ingestion

- [Dataset builder](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/build.py): `src/school_finder/data/build.py`
- [Source adapters](https://github.com/c-wilkinson/school-finder/tree/main/src/school_finder/data/sources): `src/school_finder/data/sources`
- [Parquet datasets](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/parquet.py): `src/school_finder/data/parquet.py`
- [Build manifest](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/manifest.py): `src/school_finder/data/manifest.py`
- [Historical data](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/data/history.py): `src/school_finder/data/history.py`

### Search and scoring

- [Search request](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/search.py): `src/school_finder/models/search.py`
- [Hard filters](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/filters.py): `src/school_finder/models/filters.py`
- [Preference models](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/preferences.py): `src/school_finder/models/preferences.py`
- [School models](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/school.py): `src/school_finder/models/school.py`
- [Search service](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/search.py): `src/school_finder/services/search.py`
- [Postcode lookup](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/postcode.py): `src/school_finder/services/postcode.py`
- [Preference scoring](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/scoring.py): `src/school_finder/services/scoring.py`
- [Benchmarks](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/benchmarks.py): `src/school_finder/services/benchmarks.py`
- [Subject data](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/subjects.py): `src/school_finder/services/subjects.py`
- [History service](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/services/history.py): `src/school_finder/services/history.py`

### User interfaces

- [CLI](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/cli.py): `src/school_finder/cli.py`
- [Streamlit app](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/streamlit_app.py): `src/school_finder/ui/streamlit_app.py`
- [School details](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/detail.py): `src/school_finder/ui/detail.py`
- [School comparison](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/comparison.py): `src/school_finder/ui/comparison.py`
- [Match display](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/match.py): `src/school_finder/ui/match.py`
- [Result formatting](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/formatting.py): `src/school_finder/ui/formatting.py`
- [Search controls](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/controls.py): `src/school_finder/ui/controls.py`

### Personalisation

- [Session state](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/state.py): `src/school_finder/ui/state.py`
- [Personal school state](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/models/personalisation.py): `src/school_finder/models/personalisation.py`
- [Browser persistence](https://github.com/c-wilkinson/school-finder/blob/main/src/school_finder/ui/personalisation_storage.py): `src/school_finder/ui/personalisation_storage.py`

### Other components

- **Public datasets**
- **Browser storage**

## Connections

- Public datasets → Source adapters: provides data (evidence: `README.md`)
- Dataset builder → Source adapters: loads sources (evidence: `src/school_finder/data/build.py`)
- Dataset builder → Parquet datasets: writes datasets (evidence: `src/school_finder/data/build.py`)
- Dataset builder → Build manifest: records build (evidence: `src/school_finder/data/build.py`)
- Dataset builder → Historical data: uses history (evidence: `src/school_finder/data/build.py`)
- Parquet datasets → Public datasets: stores locally (evidence: `README.md`)
- CLI → Dataset builder: runs build (evidence: `src/school_finder/cli.py`)
- CLI → Search service: runs lookup (evidence: `src/school_finder/cli.py`)
- Search request → Hard filters: defines filters (evidence: `src/school_finder/models/search.py`)
- Search request → Preference models: accepts priorities (evidence: `src/school_finder/models/search.py`)
- Search service → Parquet datasets: reads datasets (evidence: `src/school_finder/services/search.py`)
- Search service → Search request: accepts request (evidence: `src/school_finder/services/search.py`)
- Search service → Postcode lookup: resolves postcode (evidence: `src/school_finder/services/search.py`)
- Search service → Preference scoring: scores results (evidence: `src/school_finder/services/search.py`)
- Search service → Benchmarks: loads benchmarks (evidence: `src/school_finder/services/search.py`)
- Search service → School models: builds results (evidence: `src/school_finder/services/search.py`)
- Benchmarks → Parquet datasets: reads data (evidence: `src/school_finder/services/benchmarks.py`)
- History service → Historical data: reads history (evidence: `src/school_finder/services/history.py`)
- History service → Parquet datasets: reads datasets (evidence: `src/school_finder/services/history.py`)
- Subject data → Parquet datasets: reads datasets (evidence: `src/school_finder/services/subjects.py`)
- Streamlit app → Search service: runs search (evidence: `src/school_finder/ui/streamlit_app.py`)
- Streamlit app → History service: requests history (evidence: `src/school_finder/ui/streamlit_app.py`)
- Streamlit app → Subject data: requests subjects (evidence: `src/school_finder/ui/streamlit_app.py`)
- Streamlit app → Search controls: renders controls (evidence: `src/school_finder/ui/streamlit_app.py`)
- Streamlit app → School details: renders details (evidence: `src/school_finder/ui/streamlit_app.py`)
- Streamlit app → School comparison: renders comparison (evidence: `src/school_finder/ui/streamlit_app.py`)
- Streamlit app → Match display: renders matches (evidence: `src/school_finder/ui/streamlit_app.py`)
- School details → Result formatting: uses formatting (evidence: `src/school_finder/ui/detail.py`)
- School comparison → Result formatting: uses formatting (evidence: `src/school_finder/ui/comparison.py`)
- Match display → Result formatting: uses formatting (evidence: `src/school_finder/ui/match.py`)
- Streamlit app → Session state: manages state (evidence: `src/school_finder/ui/streamlit_app.py`)
- Session state → Personal school state: stores preferences (evidence: `src/school_finder/ui/state.py`)
- Streamlit app → Browser persistence: syncs personalisation (evidence: `src/school_finder/ui/streamlit_app.py`)
- Browser persistence → Personal school state: encodes state (evidence: `src/school_finder/ui/personalisation_storage.py`)
- Browser persistence → Browser storage: persists locally (evidence: `README.md`)
