# tpximpact/digital-planning-register architecture

> Architecture diagram of the GitHub repository tpximpact/digital-planning-register, 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/tpximpact/digital-planning-register
- Repository: https://github.com/tpximpact/digital-planning-register

## Overview

Digital Planning Register is a multi-council web application for finding and viewing planning records, decisions, documents and comments, and for submitting public comments. The main journey is council-scoped application search, followed by an application record and its related material; users can also search comments and documents or submit a comment through a multi-step flow. Council configuration selects segregated data sources. Source excerpts and the index show some search, configuration and handler wiring; other feature links are documented by the README or left unasserted where implementation was not sampled.

Main entry points: [`src/handlers/index.ts`](https://github.com/tpximpact/digital-planning-register/blob/main/src/handlers/index.ts) (Handler router), [`src/config/index.ts`](https://github.com/tpximpact/digital-planning-register/blob/main/src/config/index.ts) (Council config), [`src/app/[council]/page.tsx`](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/page.tsx) (Council routes), [`src/app/[council]/search-form/route.ts`](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/search-form/route.ts) (Search redirect)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_council["Council and app"]
  node_council_config["Council config<br/>[index.ts]"]
  node_council_routes["Council routes<br/>[page.tsx]"]
  node_help["Help pages<br/>[page.tsx]"]
end

subgraph group_applications["Applications"]
  node_search_form["Search forms<br/>[FormSearchFull.tsx]"]
  node_search_redirect["Search redirect<br/>[route.ts]"]
  node_app_search["Application search<br/>[search.tsx]"]
  node_search_results["Search results<br/>[PageSearch.tsx]"]
  node_application_card["Application card"]
  node_application_record["Application record<br/>[page.tsx]"]
  node_planning_domain["Planning data<br/>[decision.tsx]"]
end

subgraph group_related["Record material"]
  node_documents["Documents<br/>[documents.ts]"]
  node_document_search["Document search<br/>[route.ts]"]
  node_comments["Public comments<br/>[comments.ts]"]
  node_comment_search["Comment search<br/>[route.ts]"]
  node_specialist_comments["Specialist comments"]
  node_specialist_search["Specialist search<br/>[route.ts]"]
end

subgraph group_submission["Comment submission"]
  node_submit_comment["Comment journey<br/>[page.tsx]"]
  node_comment_api["Comment actions<br/>[v1.actions.ts]"]
end

subgraph group_data["Data access"]
  node_api_facade["API actions<br/>[index.ts]"]
  node_handler_router["Handler router<br/>[index.ts]"]
  node_external_handler["External handler<br/>[bops.ts]"]
  node_local_handlers["Local handlers<br/>[index.ts]"]
end

node_visitor(("Visitor"))
node_bops(("BOPS service"))
node_council_api(("Council API"))

node_visitor -->|"opens council"| node_council_routes
node_council_routes -->|"loads config"| node_council_config
node_council_routes -->|"uses search"| node_app_search
node_search_form -.->|"submits filters"| node_search_redirect
node_search_redirect -->|"gets config"| node_council_config
node_search_redirect -->|"validates filters"| node_app_search
node_search_results -->|"uses search"| node_app_search
node_search_results -->|"renders results"| node_application_card
node_application_record -.->|"uses planning data"| node_planning_domain
node_document_search -->|"validates filters"| node_documents
node_document_search -->|"gets config"| node_council_config
node_comment_search -->|"validates filters"| node_comments
node_specialist_search -->|"validates filters"| node_specialist_comments
node_submit_comment -->|"loads application"| node_api_facade
node_submit_comment -.->|"submits comment"| node_comment_api
node_api_facade -.->|"dispatches requests"| node_handler_router
node_handler_router -->|"reads config"| node_council_config
node_handler_router -->|"routes externally"| node_external_handler
node_handler_router -->|"routes locally"| node_local_handlers
node_external_handler -.->|"fetches council data"| node_bops
node_external_handler -.->|"fetches council data"| node_council_api

click node_council_config "https://github.com/tpximpact/digital-planning-register/blob/main/src/config/index.ts"
click node_council_routes "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/page.tsx"
click node_help "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/help/page.tsx"
click node_search_form "https://github.com/tpximpact/digital-planning-register/blob/main/src/components/FormSearchFull/FormSearchFull.tsx"
click node_search_redirect "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/search-form/route.ts"
click node_app_search "https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/planningApplication/search.tsx"
click node_search_results "https://github.com/tpximpact/digital-planning-register/blob/main/src/components/PageSearch/PageSearch.tsx"
click node_application_card "https://github.com/tpximpact/digital-planning-register/blob/main/src/components/ApplicationCard/ApplicationCard.tsx"
click node_application_record "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/page.tsx"
click node_planning_domain "https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/planningApplication/decision.tsx"
click node_documents "https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/documents.ts"
click node_document_search "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/documents/search/route.ts"
click node_comments "https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/comments.ts"
click node_comment_search "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/comments/search/route.ts"
click node_specialist_comments "https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/specialistComments.ts"
click node_specialist_search "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/specialist-comments/%5BspecialistId%5D/search/route.ts"
click node_submit_comment "https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/submit-comment/page.tsx"
click node_comment_api "https://github.com/tpximpact/digital-planning-register/blob/main/src/actions/api/v1.actions.ts"
click node_api_facade "https://github.com/tpximpact/digital-planning-register/blob/main/src/actions/api/index.ts"
click node_handler_router "https://github.com/tpximpact/digital-planning-register/blob/main/src/handlers/index.ts"
click node_external_handler "https://github.com/tpximpact/digital-planning-register/blob/main/src/handlers/external/bops.ts"
click node_local_handlers "https://github.com/tpximpact/digital-planning-register/blob/main/src/handlers/local/index.ts"

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_council_config,node_council_routes,node_help toneBlue
class node_search_form,node_search_redirect,node_app_search,node_search_results,node_application_card,node_application_record,node_planning_domain toneAmber
class node_documents,node_document_search,node_comments,node_comment_search,node_specialist_comments,node_specialist_search,node_council_api toneMint
class node_submit_comment,node_comment_api toneRose
class node_api_facade,node_handler_router,node_external_handler,node_local_handlers,node_visitor,node_bops toneIndigo
```

## Components

### Council and app

- [Council config](https://github.com/tpximpact/digital-planning-register/blob/main/src/config/index.ts): `src/config/index.ts`
- [Council routes](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/page.tsx): `src/app/[council]/page.tsx`
- [Help pages](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/help/page.tsx): `src/app/[council]/help/page.tsx`

### Applications

- [Search forms](https://github.com/tpximpact/digital-planning-register/blob/main/src/components/FormSearchFull/FormSearchFull.tsx): `src/components/FormSearchFull/FormSearchFull.tsx`
- [Search redirect](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/search-form/route.ts): `src/app/[council]/search-form/route.ts`
- [Application search](https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/planningApplication/search.tsx): `src/lib/planningApplication/search.tsx`
- [Search results](https://github.com/tpximpact/digital-planning-register/blob/main/src/components/PageSearch/PageSearch.tsx): `src/components/PageSearch/PageSearch.tsx`
- [Application card](https://github.com/tpximpact/digital-planning-register/blob/main/src/components/ApplicationCard/ApplicationCard.tsx): `src/components/ApplicationCard/ApplicationCard.tsx`
- [Application record](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/page.tsx): `src/app/[council]/[reference]/page.tsx`
- [Planning data](https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/planningApplication/decision.tsx): `src/lib/planningApplication/decision.tsx`

### Record material

- [Documents](https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/documents.ts): `src/lib/documents.ts`
- [Document search](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/documents/search/route.ts): `src/app/[council]/[reference]/documents/search/route.ts`
- [Public comments](https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/comments.ts): `src/lib/comments.ts`
- [Comment search](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/comments/search/route.ts): `src/app/[council]/[reference]/comments/search/route.ts`
- [Specialist comments](https://github.com/tpximpact/digital-planning-register/blob/main/src/lib/specialistComments.ts): `src/lib/specialistComments.ts`
- [Specialist search](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/specialist-comments/%5BspecialistId%5D/search/route.ts): `src/app/[council]/[reference]/specialist-comments/[specialistId]/search/route.ts`

### Comment submission

- [Comment journey](https://github.com/tpximpact/digital-planning-register/blob/main/src/app/%5Bcouncil%5D/%5Breference%5D/submit-comment/page.tsx): `src/app/[council]/[reference]/submit-comment/page.tsx`
- [Comment actions](https://github.com/tpximpact/digital-planning-register/blob/main/src/actions/api/v1.actions.ts): `src/actions/api/v1.actions.ts`

### Data access

- [API actions](https://github.com/tpximpact/digital-planning-register/blob/main/src/actions/api/index.ts): `src/actions/api/index.ts`
- [Handler router](https://github.com/tpximpact/digital-planning-register/blob/main/src/handlers/index.ts): `src/handlers/index.ts`
- [External handler](https://github.com/tpximpact/digital-planning-register/blob/main/src/handlers/external/bops.ts): `src/handlers/external/bops.ts`
- [Local handlers](https://github.com/tpximpact/digital-planning-register/blob/main/src/handlers/local/index.ts): `src/handlers/local/index.ts`

### Other components

- **Visitor**
- **BOPS service**
- **Council API**

## Connections

- Visitor → Council routes: opens council (evidence: `README.md`)
- Council routes → Council config: loads config (evidence: `src/app/[council]/page.tsx`)
- Council routes → Application search: uses search (evidence: `src/app/[council]/page.tsx`)
- Search forms → Search redirect: submits filters
- Search redirect → Council config: gets config (evidence: `src/app/[council]/search-form/route.ts`)
- Search redirect → Application search: validates filters (evidence: `src/app/[council]/search-form/route.ts`)
- Search results → Application search: uses search (evidence: `src/components/PageSearch/PageSearch.tsx`)
- Search results → Application card: renders results (evidence: `src/components/PageSearch/PageSearch.tsx`)
- Application record → Planning data: uses planning data
- Document search → Documents: validates filters (evidence: `src/app/[council]/[reference]/documents/search/route.ts`)
- Document search → Council config: gets config (evidence: `src/app/[council]/[reference]/documents/search/route.ts`)
- Comment search → Public comments: validates filters (evidence: `src/app/[council]/[reference]/comments/search/route.ts`)
- Specialist search → Specialist comments: validates filters (evidence: `src/app/[council]/[reference]/specialist-comments/[specialistId]/search/route.ts`)
- Comment journey → API actions: loads application (evidence: `src/app/[council]/[reference]/submit-comment/page.tsx`)
- Comment journey → Comment actions: submits comment
- API actions → Handler router: dispatches requests
- Handler router → Council config: reads config (evidence: `src/handlers/index.ts`)
- Handler router → External handler: routes externally (evidence: `src/handlers/index.ts`)
- Handler router → Local handlers: routes locally (evidence: `src/handlers/index.ts`)
- External handler → BOPS service: fetches council data
- External handler → Council API: fetches council data (evidence: `README.md`)
