# tpximpact/digital-planning-register-tools architecture

> Architecture diagram of the GitHub repository tpximpact/digital-planning-register-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tpximpact/digital-planning-register-tools
- Repository: https://github.com/tpximpact/digital-planning-register-tools

## Overview

DPR publishes public planning-application data through an API and web interface, sourcing it from local-authority ODP APIs. The clearest runtime path shown is API request routing to BOPS handlers, with legacy BOPS payload conversion into the published-application format; a separate local handler serves example datasets. The tree and README also identify an admin client-configuration interface, shared schemas, and a data-pipeline playground. Pipeline internals and the public web frontend are not shown in the excerpts, so their links are limited to documented capabilities.

Main entry points: [`apps/api/src/app.ts`](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/api/src/app.ts) (API Router), [`handlers/bops/src/modules/applications/applications.ts`](https://github.com/tpximpact/digital-planning-register-tools/blob/main/handlers/bops/src/modules/applications/applications.ts) (BOPS Application Handler), [`converters/bops/src/converters/applications/application.ts`](https://github.com/tpximpact/digital-planning-register-tools/blob/main/converters/bops/src/converters/applications/application.ts) (Application Converter), [`apps/admin/src/app/clients/actions.ts`](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/admin/src/app/clients/actions.ts) (Client Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api_app["API Router<br/>[app.ts]"]
  node_api_dispatch["Request Dispatch<br/>[handle-requests.ts]"]
  node_api_schema["API Schemas<br/>[schema.ts]"]
end

subgraph group_sources["Data Sources"]
  node_local_routes["Example API Routes<br/>[applications.ts]"]
  node_local_data["Example Data Queries<br/>[applications.ts]"]
  node_bops_handler["BOPS Application Handler<br/>[applications.ts]"]
  node_bops_other["BOPS Data Handlers"]
  node_data_pipeline["Data Pipeline"]
end

subgraph group_conversion["BOPS Conversion"]
  node_converter_app["Application Converter<br/>[application.ts]"]
  node_converter_docs["Document Converter"]
end

subgraph group_admin["Client Administration"]
  node_admin_ui["Admin Client UI"]
  node_admin_actions["Client Actions<br/>[actions.ts]"]
  node_admin_api["Internal Client API<br/>[route.ts]"]
  node_client_db[("Client Database<br/>[clients.ts]")]
end

subgraph group_shared["Shared Data"]
  node_odp_schema["Published Data Schemas"]
end

node_public_user(("API Consumer"))
node_authority{{"Authority ODP APIs"}}

node_public_user -->|"requests data"| node_api_app
node_api_app -->|"dispatches requests"| node_api_dispatch
node_api_app -->|"calls BOPS handlers"| node_bops_handler
node_api_app -->|"uses route schemas"| node_api_schema
node_api_app -.->|"serves example routes"| node_local_routes
node_local_routes -->|"queries applications"| node_local_data
node_bops_handler -.->|"fetches applications"| node_authority
node_bops_handler -->|"converts legacy payloads"| node_converter_app
node_converter_app -->|"converts attached files"| node_converter_docs
node_converter_app -.->|"produces published format"| node_odp_schema
node_local_data -.->|"queries schema-shaped data"| node_odp_schema
node_admin_ui -.->|"manages clients"| node_admin_actions
node_admin_api -->|"looks up client"| node_admin_actions
node_admin_actions -.->|"reads client records"| node_client_db
node_authority -.->|"supplies source data"| node_data_pipeline
node_data_pipeline -.->|"indexes for publication"| node_public_user

click node_api_app "https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/api/src/app.ts"
click node_api_dispatch "https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/api/src/libs/handle-requests/handle-requests.ts"
click node_api_schema "https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/api/src/schema.ts"
click node_local_routes "https://github.com/tpximpact/digital-planning-register-tools/blob/main/handlers/local/src/modules/applications/applications.ts"
click node_local_data "https://github.com/tpximpact/digital-planning-register-tools/blob/main/handlers/local/src/libs/applications/applications.ts"
click node_bops_handler "https://github.com/tpximpact/digital-planning-register-tools/blob/main/handlers/bops/src/modules/applications/applications.ts"
click node_bops_other "https://github.com/tpximpact/digital-planning-register-tools/tree/main/handlers/bops/src/modules"
click node_converter_app "https://github.com/tpximpact/digital-planning-register-tools/blob/main/converters/bops/src/converters/applications/application.ts"
click node_converter_docs "https://github.com/tpximpact/digital-planning-register-tools/blob/main/converters/bops/src/converters/documents/convertBopsFileToPostSubmissionFileRedacted.ts"
click node_odp_schema "https://github.com/tpximpact/digital-planning-register-tools/tree/main/packages/odp-schemas/src/types/schemas/postSubmissionApplication"
click node_admin_ui "https://github.com/tpximpact/digital-planning-register-tools/tree/main/apps/admin/src/app/clients"
click node_admin_actions "https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/admin/src/app/clients/actions.ts"
click node_admin_api "https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/admin/src/app/api/internal/clients/%5Bslug%5D/route.ts"
click node_client_db "https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/admin/src/db/clients.ts"
click node_data_pipeline "https://github.com/tpximpact/digital-planning-register-tools/tree/main/playground/data-pipeline/src/dpr_pipeline"

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_api_app,node_api_dispatch,node_api_schema toneBlue
class node_local_routes,node_local_data,node_bops_handler,node_bops_other,node_data_pipeline toneAmber
class node_converter_app,node_converter_docs,node_public_user,node_authority toneMint
class node_admin_ui,node_admin_actions,node_admin_api,node_client_db toneRose
class node_odp_schema toneIndigo
```

## Components

### Public API

- [API Router](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Request Dispatch](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/api/src/libs/handle-requests/handle-requests.ts): `apps/api/src/libs/handle-requests/handle-requests.ts`
- [API Schemas](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/api/src/schema.ts): `apps/api/src/schema.ts`

### Data Sources

- [Example API Routes](https://github.com/tpximpact/digital-planning-register-tools/blob/main/handlers/local/src/modules/applications/applications.ts): `handlers/local/src/modules/applications/applications.ts`
- [Example Data Queries](https://github.com/tpximpact/digital-planning-register-tools/blob/main/handlers/local/src/libs/applications/applications.ts): `handlers/local/src/libs/applications/applications.ts`
- [BOPS Application Handler](https://github.com/tpximpact/digital-planning-register-tools/blob/main/handlers/bops/src/modules/applications/applications.ts): `handlers/bops/src/modules/applications/applications.ts`
- [BOPS Data Handlers](https://github.com/tpximpact/digital-planning-register-tools/tree/main/handlers/bops/src/modules): `handlers/bops/src/modules`
- [Data Pipeline](https://github.com/tpximpact/digital-planning-register-tools/tree/main/playground/data-pipeline/src/dpr_pipeline): `playground/data-pipeline/src/dpr_pipeline`

### BOPS Conversion

- [Application Converter](https://github.com/tpximpact/digital-planning-register-tools/blob/main/converters/bops/src/converters/applications/application.ts): `converters/bops/src/converters/applications/application.ts`
- [Document Converter](https://github.com/tpximpact/digital-planning-register-tools/blob/main/converters/bops/src/converters/documents/convertBopsFileToPostSubmissionFileRedacted.ts): `converters/bops/src/converters/documents/convertBopsFileToPostSubmissionFileRedacted.ts`

### Client Administration

- [Admin Client UI](https://github.com/tpximpact/digital-planning-register-tools/tree/main/apps/admin/src/app/clients): `apps/admin/src/app/clients`
- [Client Actions](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/admin/src/app/clients/actions.ts): `apps/admin/src/app/clients/actions.ts`
- [Internal Client API](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/admin/src/app/api/internal/clients/%5Bslug%5D/route.ts): `apps/admin/src/app/api/internal/clients/[slug]/route.ts`
- [Client Database](https://github.com/tpximpact/digital-planning-register-tools/blob/main/apps/admin/src/db/clients.ts): `apps/admin/src/db/clients.ts`

### Shared Data

- [Published Data Schemas](https://github.com/tpximpact/digital-planning-register-tools/tree/main/packages/odp-schemas/src/types/schemas/postSubmissionApplication): `packages/odp-schemas/src/types/schemas/postSubmissionApplication`

### Other components

- **API Consumer**
- **Authority ODP APIs**

## Connections

- API Consumer → API Router: requests data
- API Router → Request Dispatch: dispatches requests (evidence: `apps/api/src/app.ts`)
- API Router → BOPS Application Handler: calls BOPS handlers (evidence: `apps/api/src/app.ts`)
- API Router → API Schemas: uses route schemas (evidence: `apps/api/src/app.ts`)
- API Router → Example API Routes: serves example routes
- Example API Routes → Example Data Queries: queries applications (evidence: `handlers/local/src/modules/applications/applications.ts`)
- BOPS Application Handler → Authority ODP APIs: fetches applications
- BOPS Application Handler → Application Converter: converts legacy payloads (evidence: `handlers/bops/src/modules/applications/applications.ts`)
- Application Converter → Document Converter: converts attached files (evidence: `converters/bops/src/converters/applications/application.ts`)
- Application Converter → Published Data Schemas: produces published format
- Example Data Queries → Published Data Schemas: queries schema-shaped data
- Admin Client UI → Client Actions: manages clients
- Internal Client API → Client Actions: looks up client (evidence: `apps/admin/src/app/api/internal/clients/[slug]/route.ts`)
- Client Actions → Client Database: reads client records
- Authority ODP APIs → Data Pipeline: supplies source data
- Data Pipeline → API Consumer: indexes for publication
