# onsdigital/address-index-api architecture

> Architecture diagram of the GitHub repository onsdigital/address-index-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onsdigital/address-index-api
- Repository: https://github.com/onsdigital/address-index-api

## Overview

Address Index is a Play API for resolving submitted addresses to likely indexed records and UPRNs, with a demo UI as one client. The main workflow is address input → request validation → Elasticsearch search → formatted match response; batch matching follows the same purpose at batch scale. Separate API capabilities include UPRN, postcode, partial-address/typeahead, and other specialized searches. The graph also shows the UI client and the Elasticsearch boundary. README and sampled excerpts support the broad capability map, but unsampled controller-to-repository wiring is shown only where evidence supports it.

Main entry points: [`server/app/uk/gov/ons/addressIndex/server/modules/ElasticsearchRepository.scala`](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/modules/ElasticsearchRepository.scala) (Search repository), [`client/src/main/scala/uk/gov/ons/addressIndex/client/AddressIndexClient.scala`](https://github.com/onsdigital/address-index-api/blob/develop/client/src/main/scala/uk/gov/ons/addressIndex/client/AddressIndexClient.scala) (API client), [`server/app/uk/gov/ons/addressIndex/server/controllers/AddressController.scala`](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/AddressController.scala) (Address matching), [`model/src/main/scala/uk/gov/ons/addressIndex/model/server/response`](https://github.com/onsdigital/address-index-api/tree/develop/model/src/main/scala/uk/gov/ons/addressIndex/model/server/response) (API response models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Demo UI"]
  node_ui_match["Single match"]
  node_ui_bulk["Bulk match"]
  node_ui_clerical["Clerical search"]
  node_ui_other["Other searches"]
  node_client["API client"]
end

subgraph group_api["API endpoints"]
  node_address["Address matching"]
  node_batch["Batch matching"]
  node_uprn["UPRN lookup"]
  node_postcode["Postcode search"]
  node_partial["Partial search"]
  node_special["Specialized searches"]
end

subgraph group_search["Search runtime"]
  node_validation["Request validation"]
  node_repository["Search repository"]
end

subgraph group_contracts["Models and responses"]
  node_queryvalues["Query parameters<br/>[QueryValues.scala]"]
  node_indexmodels["Indexed address models"]
  node_responsemodels["API response models"]
end

node_user(("API or UI user"))
node_es[("Elasticsearch index")]

node_user -->|"submits address"| node_ui_match
node_user -->|"submits batch"| node_ui_bulk
node_user -->|"requests review"| node_ui_clerical
node_user -->|"calls API"| node_client
node_ui_match -->|"calls"| node_client
node_ui_bulk -->|"calls"| node_client
node_ui_clerical -->|"calls"| node_client
node_ui_other -->|"calls"| node_client
node_client -->|"sends query"| node_address
node_client -->|"sends batch"| node_batch
node_address -->|"validates"| node_validation
node_address -->|"searches"| node_repository
node_batch -->|"validates"| node_validation
node_batch -->|"bulk searches"| node_repository
node_uprn -->|"looks up"| node_repository
node_postcode -->|"searches"| node_repository
node_partial -->|"validates"| node_validation
node_partial -->|"searches"| node_repository
node_special -->|"searches"| node_repository
node_repository -->|"queries"| node_es
node_repository -->|"returns records"| node_indexmodels
node_address -->|"builds parameters"| node_queryvalues
node_validation -->|"checks parameters"| node_queryvalues
node_address -->|"formats response"| node_responsemodels
node_uprn -->|"formats response"| node_responsemodels
node_postcode -->|"formats response"| node_responsemodels
node_partial -->|"formats response"| node_responsemodels
node_batch -->|"formats response"| node_responsemodels

click node_ui_match "https://github.com/onsdigital/address-index-api/blob/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/SingleMatchController.scala"
click node_ui_bulk "https://github.com/onsdigital/address-index-api/blob/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/BulkMatchController.scala"
click node_ui_clerical "https://github.com/onsdigital/address-index-api/blob/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/ClericalToolController.scala"
click node_ui_other "https://github.com/onsdigital/address-index-api/tree/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers"
click node_client "https://github.com/onsdigital/address-index-api/blob/develop/client/src/main/scala/uk/gov/ons/addressIndex/client/AddressIndexClient.scala"
click node_address "https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/AddressController.scala"
click node_batch "https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/BatchController.scala"
click node_uprn "https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/UPRNController.scala"
click node_postcode "https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/PostcodeController.scala"
click node_partial "https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/PartialAddressController.scala"
click node_special "https://github.com/onsdigital/address-index-api/tree/develop/server/app/uk/gov/ons/addressIndex/server/controllers"
click node_validation "https://github.com/onsdigital/address-index-api/tree/develop/server/app/uk/gov/ons/addressIndex/server/modules/validation"
click node_repository "https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/modules/ElasticsearchRepository.scala"
click node_queryvalues "https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/model/dao/QueryValues.scala"
click node_indexmodels "https://github.com/onsdigital/address-index-api/tree/develop/model/src/main/scala/uk/gov/ons/addressIndex/model/db/index"
click node_responsemodels "https://github.com/onsdigital/address-index-api/tree/develop/model/src/main/scala/uk/gov/ons/addressIndex/model/server/response"

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_ui_match,node_ui_bulk,node_ui_clerical,node_ui_other,node_client,node_user toneBlue
class node_address,node_batch,node_uprn,node_postcode,node_partial,node_special,node_es toneAmber
class node_validation,node_repository toneMint
class node_queryvalues,node_indexmodels,node_responsemodels toneRose
```

## Components

### Demo UI

- [Single match](https://github.com/onsdigital/address-index-api/blob/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/SingleMatchController.scala): `demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/SingleMatchController.scala`
- [Bulk match](https://github.com/onsdigital/address-index-api/blob/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/BulkMatchController.scala): `demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/BulkMatchController.scala`
- [Clerical search](https://github.com/onsdigital/address-index-api/blob/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/ClericalToolController.scala): `demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers/ClericalToolController.scala`
- [Other searches](https://github.com/onsdigital/address-index-api/tree/develop/demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers): `demo-ui/app/uk/gov/ons/addressIndex/demoui/controllers`
- [API client](https://github.com/onsdigital/address-index-api/blob/develop/client/src/main/scala/uk/gov/ons/addressIndex/client/AddressIndexClient.scala): `client/src/main/scala/uk/gov/ons/addressIndex/client/AddressIndexClient.scala`

### API endpoints

- [Address matching](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/AddressController.scala): `server/app/uk/gov/ons/addressIndex/server/controllers/AddressController.scala`
- [Batch matching](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/BatchController.scala): `server/app/uk/gov/ons/addressIndex/server/controllers/BatchController.scala`
- [UPRN lookup](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/UPRNController.scala): `server/app/uk/gov/ons/addressIndex/server/controllers/UPRNController.scala`
- [Postcode search](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/PostcodeController.scala): `server/app/uk/gov/ons/addressIndex/server/controllers/PostcodeController.scala`
- [Partial search](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/controllers/PartialAddressController.scala): `server/app/uk/gov/ons/addressIndex/server/controllers/PartialAddressController.scala`
- [Specialized searches](https://github.com/onsdigital/address-index-api/tree/develop/server/app/uk/gov/ons/addressIndex/server/controllers): `server/app/uk/gov/ons/addressIndex/server/controllers`

### Search runtime

- [Request validation](https://github.com/onsdigital/address-index-api/tree/develop/server/app/uk/gov/ons/addressIndex/server/modules/validation): `server/app/uk/gov/ons/addressIndex/server/modules/validation`
- [Search repository](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/modules/ElasticsearchRepository.scala): `server/app/uk/gov/ons/addressIndex/server/modules/ElasticsearchRepository.scala`

### Models and responses

- [Query parameters](https://github.com/onsdigital/address-index-api/blob/develop/server/app/uk/gov/ons/addressIndex/server/model/dao/QueryValues.scala): `server/app/uk/gov/ons/addressIndex/server/model/dao/QueryValues.scala`
- [Indexed address models](https://github.com/onsdigital/address-index-api/tree/develop/model/src/main/scala/uk/gov/ons/addressIndex/model/db/index): `model/src/main/scala/uk/gov/ons/addressIndex/model/db/index`
- [API response models](https://github.com/onsdigital/address-index-api/tree/develop/model/src/main/scala/uk/gov/ons/addressIndex/model/server/response): `model/src/main/scala/uk/gov/ons/addressIndex/model/server/response`

### Other components

- **API or UI user**
- **Elasticsearch index**

## Connections

- API or UI user → Single match: submits address
- API or UI user → Bulk match: submits batch
- API or UI user → Clerical search: requests review
- API or UI user → API client: calls API
- Single match → API client: calls
- Bulk match → API client: calls
- Clerical search → API client: calls
- Other searches → API client: calls
- API client → Address matching: sends query
- API client → Batch matching: sends batch
- Address matching → Request validation: validates
- Address matching → Search repository: searches
- Batch matching → Request validation: validates
- Batch matching → Search repository: bulk searches
- UPRN lookup → Search repository: looks up
- Postcode search → Search repository: searches
- Partial search → Request validation: validates
- Partial search → Search repository: searches
- Specialized searches → Search repository: searches
- Search repository → Elasticsearch index: queries
- Search repository → Indexed address models: returns records
- Address matching → Query parameters: builds parameters
- Request validation → Query parameters: checks parameters
- Address matching → API response models: formats response
- UPRN lookup → API response models: formats response
- Postcode search → API response models: formats response
- Partial search → API response models: formats response
- Batch matching → API response models: formats response