# tom-draper/uk-data-atlas architecture

> Architecture diagram of the GitHub repository tom-draper/uk-data-atlas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tom-draper/uk-data-atlas
- Repository: https://github.com/tom-draper/uk-data-atlas

## Overview

UK Data Atlas is a web mapping platform for exploring UK geographic datasets. Users select a location and visualization, load the corresponding data and boundaries, and inspect the result as a map with chart and legend controls. The repository also contains a geography and data API, plus place and reference pages. The frontend excerpts show the Atlas-to-map handoff and map-layer management; the API excerpts show measure-coverage handling. Other API capabilities are represented from the source index, so their internal route wiring is not asserted.

Main entry points: [`components/AtlasClient.tsx`](https://github.com/tom-draper/uk-data-atlas/blob/main/components/AtlasClient.tsx) (Atlas client), [`components/MapInterface.tsx`](https://github.com/tom-draper/uk-data-atlas/blob/main/components/MapInterface.tsx) (Map interface), [`services/api/src/routing.ts`](https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/routing.ts) (API routing), [`services/api/src/measureCoverageRoutes.ts`](https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/measureCoverageRoutes.ts) (Measure coverage route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_atlas["Atlas experience"]
  node_atlas_pages["Atlas pages<br/>[page.tsx]"]
  node_atlas_client["Atlas client<br/>[AtlasClient.tsx]"]
end

subgraph group_visualization["Map visualization"]
  node_map_interface["Map interface<br/>[MapInterface.tsx]"]
  node_map_session["Map session<br/>[useMapSession.ts]"]
  node_map_manager_hook["Map manager hook<br/>[useMapManager.ts]"]
  node_map_manager["Map manager<br/>[mapManager.ts]"]
  node_layer_manager["Layer manager<br/>[layerManager.ts]"]
  node_chart_panels["Chart panels<br/>[ChartSections.tsx]"]
  node_map_controls["Map controls<br/>[MapOptions.tsx]"]
end

subgraph group_data["Data and geography"]
  node_dataset_registry["Chart dataset registry<br/>[index.ts]"]
  node_dataset_catalog["Dataset catalogue<br/>[index.ts]"]
  node_dataset_loaders["Dataset loading"]
  node_boundary_data["Boundary data<br/>[worker.ts]"]
end

subgraph group_api["Geography API"]
  node_api_router["API routing<br/>[routing.ts]"]
  node_api_measure_routes["Measure coverage route"]
  node_api_response["API responses<br/>[routeResponse.ts]"]
  node_api_area_resources["Area resources<br/>[areaResources.ts]"]
  node_api_geo_services["Geography services"]
  node_api_data_services["Data services"]
end

subgraph group_discovery["Places and reference"]
  node_place_data["Place profiles<br/>[load.ts]"]
  node_reference_pages["Reference pages<br/>[ReferencePage.tsx]"]
end

node_visitor(("Atlas visitor"))

node_visitor -->|"opens"| node_atlas_pages
node_atlas_pages -->|"renders"| node_atlas_client
node_atlas_client -->|"renders"| node_map_interface
node_atlas_client -->|"loads datasets"| node_dataset_loaders
node_atlas_client -.->|"reports boundary errors"| node_boundary_data
node_map_interface -.->|"configures"| node_map_session
node_map_session -->|"uses"| node_map_manager_hook
node_map_manager_hook -->|"creates"| node_map_manager
node_map_manager -->|"delegates layers"| node_layer_manager
node_map_interface -.->|"renders"| node_chart_panels
node_map_interface -.->|"renders"| node_map_controls
node_dataset_registry -.->|"defines datasets"| node_dataset_loaders
node_dataset_catalog -.->|"catalogues data"| node_dataset_loaders
node_visitor -->|"browses"| node_reference_pages
node_api_router -.->|"dispatches"| node_api_measure_routes
node_api_measure_routes -->|"formats response"| node_api_response
node_api_measure_routes -->|"checks area"| node_api_area_resources
node_api_router -.->|"routes geography requests"| node_api_geo_services
node_api_router -.->|"routes data requests"| node_api_data_services
node_visitor -->|"views place profiles"| node_place_data

click node_atlas_pages "https://github.com/tom-draper/uk-data-atlas/blob/main/app/atlas/page.tsx"
click node_atlas_client "https://github.com/tom-draper/uk-data-atlas/blob/main/components/AtlasClient.tsx"
click node_map_interface "https://github.com/tom-draper/uk-data-atlas/blob/main/components/MapInterface.tsx"
click node_map_session "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/hooks/useMapSession.ts"
click node_map_manager_hook "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/hooks/useMapManager.ts"
click node_map_manager "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/helpers/mapManager/mapManager.ts"
click node_layer_manager "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/helpers/mapManager/layerManager.ts"
click node_chart_panels "https://github.com/tom-draper/uk-data-atlas/blob/main/components/ChartSections.tsx"
click node_map_controls "https://github.com/tom-draper/uk-data-atlas/blob/main/components/MapOptions.tsx"
click node_dataset_registry "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/datasets/index.ts"
click node_dataset_catalog "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/data/catalog/index.ts"
click node_dataset_loaders "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/data/jsonDatasetClient.ts"
click node_boundary_data "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/data/boundaries/worker.ts"
click node_place_data "https://github.com/tom-draper/uk-data-atlas/blob/main/lib/places/load.ts"
click node_reference_pages "https://github.com/tom-draper/uk-data-atlas/blob/main/components/reference/ReferencePage.tsx"
click node_api_router "https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/routing.ts"
click node_api_measure_routes "https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/measureCoverageRoutes.ts"
click node_api_response "https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/routeResponse.ts"
click node_api_area_resources "https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/areaResources.ts"
click node_api_geo_services "https://github.com/tom-draper/uk-data-atlas/tree/main/services/api/src"
click node_api_data_services "https://github.com/tom-draper/uk-data-atlas/tree/main/services/api/src"

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_atlas_pages,node_atlas_client toneBlue
class node_map_interface,node_map_session,node_map_manager_hook,node_map_manager,node_layer_manager,node_chart_panels,node_map_controls toneAmber
class node_dataset_registry,node_dataset_catalog,node_dataset_loaders,node_boundary_data toneMint
class node_api_router,node_api_measure_routes,node_api_response,node_api_area_resources,node_api_geo_services,node_api_data_services toneRose
class node_place_data,node_reference_pages,node_visitor toneIndigo
```

## Components

### Atlas experience

- [Atlas pages](https://github.com/tom-draper/uk-data-atlas/blob/main/app/atlas/page.tsx): `app/atlas/page.tsx`
- [Atlas client](https://github.com/tom-draper/uk-data-atlas/blob/main/components/AtlasClient.tsx): `components/AtlasClient.tsx`

### Map visualization

- [Map interface](https://github.com/tom-draper/uk-data-atlas/blob/main/components/MapInterface.tsx): `components/MapInterface.tsx`
- [Map session](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/hooks/useMapSession.ts): `lib/hooks/useMapSession.ts`
- [Map manager hook](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/hooks/useMapManager.ts): `lib/hooks/useMapManager.ts`
- [Map manager](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/helpers/mapManager/mapManager.ts): `lib/helpers/mapManager/mapManager.ts`
- [Layer manager](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/helpers/mapManager/layerManager.ts): `lib/helpers/mapManager/layerManager.ts`
- [Chart panels](https://github.com/tom-draper/uk-data-atlas/blob/main/components/ChartSections.tsx): `components/ChartSections.tsx`
- [Map controls](https://github.com/tom-draper/uk-data-atlas/blob/main/components/MapOptions.tsx): `components/MapOptions.tsx`

### Data and geography

- [Chart dataset registry](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/datasets/index.ts): `lib/datasets/index.ts`
- [Dataset catalogue](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/data/catalog/index.ts): `lib/data/catalog/index.ts`
- [Dataset loading](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/data/jsonDatasetClient.ts): `lib/data/jsonDatasetClient.ts`
- [Boundary data](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/data/boundaries/worker.ts): `lib/data/boundaries/worker.ts`

### Geography API

- [API routing](https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/routing.ts): `services/api/src/routing.ts`
- [Measure coverage route](https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/measureCoverageRoutes.ts): `services/api/src/measureCoverageRoutes.ts`
- [API responses](https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/routeResponse.ts): `services/api/src/routeResponse.ts`
- [Area resources](https://github.com/tom-draper/uk-data-atlas/blob/main/services/api/src/areaResources.ts): `services/api/src/areaResources.ts`
- [Geography services](https://github.com/tom-draper/uk-data-atlas/tree/main/services/api/src): `services/api/src`
- [Data services](https://github.com/tom-draper/uk-data-atlas/tree/main/services/api/src): `services/api/src`

### Places and reference

- [Place profiles](https://github.com/tom-draper/uk-data-atlas/blob/main/lib/places/load.ts): `lib/places/load.ts`
- [Reference pages](https://github.com/tom-draper/uk-data-atlas/blob/main/components/reference/ReferencePage.tsx): `components/reference/ReferencePage.tsx`

### Other components

- **Atlas visitor**

## Connections

- Atlas visitor → Atlas pages: opens
- Atlas pages → Atlas client: renders (evidence: `app/atlas/page.tsx`)
- Atlas client → Map interface: renders (evidence: `components/AtlasClient.tsx`)
- Atlas client → Dataset loading: loads datasets (evidence: `components/AtlasClient.tsx`)
- Atlas client → Boundary data: reports boundary errors
- Map interface → Map session: configures
- Map session → Map manager hook: uses (evidence: `lib/hooks/useMapSession.ts`)
- Map manager hook → Map manager: creates (evidence: `lib/hooks/useMapManager.ts`)
- Map manager → Layer manager: delegates layers (evidence: `lib/helpers/mapManager/mapManager.ts`)
- Map interface → Chart panels: renders
- Map interface → Map controls: renders
- Chart dataset registry → Dataset loading: defines datasets
- Dataset catalogue → Dataset loading: catalogues data
- Atlas visitor → Reference pages: browses
- API routing → Measure coverage route: dispatches (evidence: `services/api/src/measureCoverageRoutes.ts`)
- Measure coverage route → API responses: formats response (evidence: `services/api/src/measureCoverageRoutes.ts`)
- Measure coverage route → Area resources: checks area (evidence: `services/api/src/measureCoverageRoutes.ts`)
- API routing → Geography services: routes geography requests (evidence: `services/api/src/routing.ts`)
- API routing → Data services: routes data requests (evidence: `services/api/src/routing.ts`)
- Atlas visitor → Place profiles: views place profiles
