# hmcts/nfdiv-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/hmcts/nfdiv-frontend
- Repository: https://github.com/hmcts/nfdiv-frontend

## Overview

nfdiv-frontend is an Express web application for citizens applying for divorce and managing related court applications. A user enters through the routed step journeys, provides eligibility, jurisdiction and application details, then pays and submits; later journeys include service applications, evidence uploads and case updates. Controllers use the case API client and session-held case data, with separate integrations for identity, payments and document management. README documents case orchestration and document download; the sampled files show controller behavior, but not every integration’s wiring.

Main entry points: [`src/main/server.ts`](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/server.ts) (Express server), [`src/main/app/case/case-api-client.ts`](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/case/case-api-client.ts) (Case API client), [`src/main/routes.ts`](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/routes.ts) (HTTP routes), [`src/main/app/controller/BasePaymentPostController.ts`](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/controller/BasePaymentPostController.ts) (Payment controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web entry"]
  node_server["Express server<br/>[server.ts]"]
  node_routes["HTTP routes<br/>[routes.ts]"]
end

subgraph group_journeys["Citizen journeys"]
  node_steps["Application steps"]
  node_alternative["Alternative service"]
  node_dispense["Dispense service"]
  node_controllers["Form controllers<br/>[PostController.ts]"]
  node_jurisdiction["Jurisdiction logic"]
  node_access["Access code"]
  node_paymentflow["Payment controller"]
  node_documents["Document management"]
end

subgraph group_case["Case services"]
  node_caseapi["Case API client<br/>[case-api-client.ts]"]
  node_caseformat["Case formatting<br/>[to-api-format.ts]"]
  node_docclient["Document API client"]
end

subgraph group_integrations["External integrations"]
  node_casebackend["Case orchestration"]
  node_paymentclient["Payment client<br/>[PaymentClient.ts]"]
  node_payments["Payment service"]
  node_docservice["Document service"]
  node_identity["Identity provider"]
end

subgraph group_platform["Web platform"]
  node_oidc["OIDC middleware<br/>[index.ts]"]
  node_session[("Session storage<br/>[index.ts]")]
  node_render["Page rendering<br/>[index.ts]"]
  node_errors["Error handling<br/>[index.ts]"]
end

node_citizen(("Citizen"))

node_citizen -->|"sends requests"| node_server
node_server -->|"registers routes"| node_routes
node_routes -->|"dispatches journey"| node_steps
node_steps -->|"selects handlers"| node_controllers
node_controllers -->|"triggers case events"| node_caseapi
node_jurisdiction -->|"saves jurisdiction"| node_caseapi
node_access -->|"retrieves and links"| node_caseapi
node_caseapi -->|"formats case data"| node_caseformat
node_caseapi -->|"requests case actions"| node_casebackend
node_paymentflow -->|"updates payment case"| node_caseapi
node_paymentflow -->|"creates payment"| node_paymentclient
node_paymentclient -->|"requests payment"| node_payments
node_documents -->|"uploads or deletes"| node_docclient
node_docclient -->|"transfers documents"| node_docservice
node_server -->|"installs middleware"| node_oidc
node_oidc -->|"authenticates users"| node_identity
node_server -->|"enables sessions"| node_session
node_server -->|"configures rendering"| node_render
node_server -->|"installs handler"| node_errors
node_routes -->|"routes journey"| node_alternative
node_routes -->|"routes journey"| node_dispense

click node_server "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/server.ts"
click node_routes "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/routes.ts"
click node_steps "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/steps/applicant1Sequence.ts"
click node_alternative "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/steps/alternativeServiceApplicationSequence.ts"
click node_dispense "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/steps/dispenseServiceApplicationSequence.ts"
click node_controllers "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/controller/PostController.ts"
click node_jurisdiction "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/jurisdiction/JurisdictionPostController.ts"
click node_access "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/access-code/AccessCodePostController.ts"
click node_caseapi "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/case/case-api-client.ts"
click node_caseformat "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/case/to-api-format.ts"
click node_paymentflow "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/controller/BasePaymentPostController.ts"
click node_paymentclient "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/payment/PaymentClient.ts"
click node_documents "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/document/DocumentManagementController.ts"
click node_docclient "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/document/CaseDocumentManagementClient.ts"
click node_oidc "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/oidc/index.ts"
click node_session "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/session/index.ts"
click node_render "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/nunjucks/index.ts"
click node_errors "https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/error-handler/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_server,node_routes toneBlue
class node_steps,node_alternative,node_dispense,node_controllers,node_jurisdiction,node_access,node_paymentflow,node_documents toneAmber
class node_caseapi,node_caseformat,node_docclient toneMint
class node_casebackend,node_paymentclient,node_payments,node_docservice,node_identity toneRose
class node_oidc,node_session,node_render,node_errors,node_citizen toneIndigo
```

## Components

### Web entry

- [Express server](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/server.ts): `src/main/server.ts`
- [HTTP routes](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/routes.ts): `src/main/routes.ts`

### Citizen journeys

- [Application steps](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/steps/applicant1Sequence.ts): `src/main/steps/applicant1Sequence.ts`
- [Alternative service](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/steps/alternativeServiceApplicationSequence.ts): `src/main/steps/alternativeServiceApplicationSequence.ts`
- [Dispense service](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/steps/dispenseServiceApplicationSequence.ts): `src/main/steps/dispenseServiceApplicationSequence.ts`
- [Form controllers](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/controller/PostController.ts): `src/main/app/controller/PostController.ts`
- [Jurisdiction logic](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/jurisdiction/JurisdictionPostController.ts): `src/main/app/jurisdiction/JurisdictionPostController.ts`
- [Access code](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/access-code/AccessCodePostController.ts): `src/main/app/access-code/AccessCodePostController.ts`
- [Payment controller](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/controller/BasePaymentPostController.ts): `src/main/app/controller/BasePaymentPostController.ts`
- [Document management](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/document/DocumentManagementController.ts): `src/main/app/document/DocumentManagementController.ts`

### Case services

- [Case API client](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/case/case-api-client.ts): `src/main/app/case/case-api-client.ts`
- [Case formatting](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/case/to-api-format.ts): `src/main/app/case/to-api-format.ts`
- [Document API client](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/document/CaseDocumentManagementClient.ts): `src/main/app/document/CaseDocumentManagementClient.ts`

### External integrations

- **Case orchestration**
- [Payment client](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/app/payment/PaymentClient.ts): `src/main/app/payment/PaymentClient.ts`
- **Payment service**
- **Document service**
- **Identity provider**

### Web platform

- [OIDC middleware](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/oidc/index.ts): `src/main/modules/oidc/index.ts`
- [Session storage](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/session/index.ts): `src/main/modules/session/index.ts`
- [Page rendering](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/nunjucks/index.ts): `src/main/modules/nunjucks/index.ts`
- [Error handling](https://github.com/hmcts/nfdiv-frontend/blob/master/src/main/modules/error-handler/index.ts): `src/main/modules/error-handler/index.ts`

### Other components

- **Citizen**

## Connections

- Citizen → Express server: sends requests
- Express server → HTTP routes: registers routes
- HTTP routes → Application steps: dispatches journey
- Application steps → Form controllers: selects handlers
- Form controllers → Case API client: triggers case events
- Jurisdiction logic → Case API client: saves jurisdiction
- Access code → Case API client: retrieves and links
- Case API client → Case formatting: formats case data
- Case API client → Case orchestration: requests case actions
- Payment controller → Case API client: updates payment case
- Payment controller → Payment client: creates payment
- Payment client → Payment service: requests payment
- Document management → Document API client: uploads or deletes
- Document API client → Document service: transfers documents
- Express server → OIDC middleware: installs middleware
- OIDC middleware → Identity provider: authenticates users
- Express server → Session storage: enables sessions
- Express server → Page rendering: configures rendering
- Express server → Error handling: installs handler
- HTTP routes → Alternative service: routes journey
- HTTP routes → Dispense service: routes journey