# govuk-one-login/authentication-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/govuk-one-login/authentication-frontend
- Repository: https://github.com/govuk-one-login/authentication-frontend

## Overview

This is GOV.UK One Login’s authentication frontend: an Express web application that handles OIDC authorization and guides users through sign-in, account creation, verification, MFA, and related recovery journeys. Its state machine tracks journey transitions in the user session; controllers implement individual steps and shared services handle verification, notifications, and passkeys. The README also describes an orchestration stub used to initiate local OIDC flows. Some service integrations are represented as unverified because the sampled excerpts do not show their runtime calls.

Main entry points: [`src/components/common/state-machine/state-machine-executor.ts`](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/state-machine/state-machine-executor.ts) (Journey executor), [`src/app.ts`](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/app.ts) (Express app), [`src/components/common/send-notification/send-notification-service.ts`](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/send-notification/send-notification-service.ts) (Notifications), [`src/components/authorize/authorize-controller.ts`](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/authorize/authorize-controller.ts) (OIDC authorize)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web entry"]
  node_app["Express app<br/>[app.ts]"]
  node_session["Session middleware"]
  node_templates["Page templates<br/>[pages.ts]"]
end

subgraph group_journey["Authentication journeys"]
  node_authorize["OIDC authorize"]
  node_journey_machine["Journey state machine<br/>[state-machine.ts]"]
  node_journey_executor["Journey executor"]
  node_email["Email entry"]
  node_phone["Phone verification"]
  node_auth_app["Authenticator setup"]
  node_auth_code["Authenticator code"]
  node_passkeys["Passkey journeys"]
  node_ipv["Identity callbacks"]
  node_mfa_reset["MFA reset"]
  node_recovery["Account recovery"]
end

subgraph group_shared["Journey services"]
  node_verify_mfa["MFA verification"]
  node_notifications["Notifications"]
  node_passkey_service["Passkey service<br/>[passkey-service.ts]"]
  node_http["HTTP utilities<br/>[http.ts]"]
end

subgraph group_support["User support"]
  node_contact["Contact support"]
end

subgraph group_integration["External systems"]
  node_api{{"Authentication API"}}
  node_notify{{"Notification service"}}
  node_session_store[("Session store")]
  node_orch_stub{{"Orchestration stub"}}
end

node_user(("User"))

node_user -->|"starts journey"| node_app
node_app -->|"installs middleware"| node_session
node_session -.->|"configures sessions"| node_session_store
node_app -->|"routes requests"| node_authorize
node_authorize -->|"updates journey"| node_journey_executor
node_journey_executor -->|"gets next state"| node_journey_machine
node_journey_executor -->|"saves journey state"| node_session
node_journey_executor -->|"checks prompts"| node_passkey_service
node_email -->|"sends codes"| node_notifications
node_phone -->|"sends codes"| node_notifications
node_phone -->|"verifies code"| node_verify_mfa
node_auth_app -->|"sends codes"| node_notifications
node_auth_app -->|"verifies code"| node_verify_mfa
node_auth_code -->|"verifies code"| node_verify_mfa
node_passkeys -.->|"uses passkeys"| node_passkey_service
node_ipv -.->|"handles recovery"| node_recovery
node_mfa_reset -.->|"continues identity flow"| node_ipv
node_contact -->|"renders pages"| node_templates
node_authorize -.->|"requests authorization"| node_api
node_notifications -.->|"delivers messages"| node_notify
node_orch_stub -->|"initiates OIDC flow"| node_app

click node_app "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/app.ts"
click node_session "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/middleware/session-middleware.ts"
click node_authorize "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/authorize/authorize-controller.ts"
click node_journey_machine "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/state-machine/state-machine.ts"
click node_journey_executor "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/state-machine/state-machine-executor.ts"
click node_email "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/enter-email/enter-email-controller.ts"
click node_phone "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/check-your-phone/check-your-phone-controller.ts"
click node_auth_app "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/setup-authenticator-app/setup-authenticator-app-controller.ts"
click node_auth_code "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/enter-authenticator-app-code/enter-authenticator-app-code-controller.ts"
click node_passkeys "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/create-passkey/create-passkey-controller.ts"
click node_ipv "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/ipv-callback/ipv-callback-controller.ts"
click node_mfa_reset "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/mfa-reset-with-ipv/mfa-reset-with-ipv-controller.ts"
click node_recovery "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/account-recovery/account-recovery-service.ts"
click node_verify_mfa "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/verify-mfa-code/verify-mfa-code-service.ts"
click node_notifications "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/send-notification/send-notification-service.ts"
click node_passkey_service "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/passkey/passkey-service.ts"
click node_http "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/utils/http.ts"
click node_templates "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/templates/pages.ts"
click node_contact "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/contact-us/contact-us-controller.ts"
click node_session_store "https://github.com/govuk-one-login/authentication-frontend/blob/main/src/config/dynamodb-session.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_app,node_session,node_templates,node_user toneBlue
class node_authorize,node_journey_machine,node_journey_executor,node_email,node_phone,node_auth_app,node_auth_code,node_passkeys,node_ipv,node_mfa_reset,node_recovery toneAmber
class node_verify_mfa,node_notifications,node_passkey_service,node_http toneMint
class node_contact toneRose
class node_api,node_notify,node_session_store,node_orch_stub toneIndigo
```

## Components

### Web entry

- [Express app](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/app.ts): `src/app.ts`
- [Session middleware](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/middleware/session-middleware.ts): `src/middleware/session-middleware.ts`
- [Page templates](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/templates/pages.ts): `src/components/templates/pages.ts`

### Authentication journeys

- [OIDC authorize](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/authorize/authorize-controller.ts): `src/components/authorize/authorize-controller.ts`
- [Journey state machine](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/state-machine/state-machine.ts): `src/components/common/state-machine/state-machine.ts`
- [Journey executor](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/state-machine/state-machine-executor.ts): `src/components/common/state-machine/state-machine-executor.ts`
- [Email entry](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/enter-email/enter-email-controller.ts): `src/components/enter-email/enter-email-controller.ts`
- [Phone verification](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/check-your-phone/check-your-phone-controller.ts): `src/components/check-your-phone/check-your-phone-controller.ts`
- [Authenticator setup](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/setup-authenticator-app/setup-authenticator-app-controller.ts): `src/components/setup-authenticator-app/setup-authenticator-app-controller.ts`
- [Authenticator code](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/enter-authenticator-app-code/enter-authenticator-app-code-controller.ts): `src/components/enter-authenticator-app-code/enter-authenticator-app-code-controller.ts`
- [Passkey journeys](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/create-passkey/create-passkey-controller.ts): `src/components/create-passkey/create-passkey-controller.ts`
- [Identity callbacks](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/ipv-callback/ipv-callback-controller.ts): `src/components/ipv-callback/ipv-callback-controller.ts`
- [MFA reset](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/mfa-reset-with-ipv/mfa-reset-with-ipv-controller.ts): `src/components/mfa-reset-with-ipv/mfa-reset-with-ipv-controller.ts`
- [Account recovery](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/account-recovery/account-recovery-service.ts): `src/components/common/account-recovery/account-recovery-service.ts`

### Journey services

- [MFA verification](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/verify-mfa-code/verify-mfa-code-service.ts): `src/components/common/verify-mfa-code/verify-mfa-code-service.ts`
- [Notifications](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/send-notification/send-notification-service.ts): `src/components/common/send-notification/send-notification-service.ts`
- [Passkey service](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/common/passkey/passkey-service.ts): `src/components/common/passkey/passkey-service.ts`
- [HTTP utilities](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/utils/http.ts): `src/utils/http.ts`

### User support

- [Contact support](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/components/contact-us/contact-us-controller.ts): `src/components/contact-us/contact-us-controller.ts`

### External systems

- **Authentication API**
- **Notification service**
- [Session store](https://github.com/govuk-one-login/authentication-frontend/blob/main/src/config/dynamodb-session.ts): `src/config/dynamodb-session.ts`
- **Orchestration stub**

### Other components

- **User**

## Connections

- User → Express app: starts journey
- Express app → Session middleware: installs middleware (evidence: `src/app.ts`)
- Session middleware → Session store: configures sessions
- Express app → OIDC authorize: routes requests (evidence: `src/app.ts`)
- OIDC authorize → Journey executor: updates journey (evidence: `src/components/authorize/authorize-controller.ts`)
- Journey executor → Journey state machine: gets next state (evidence: `src/components/common/state-machine/state-machine-executor.ts`)
- Journey executor → Session middleware: saves journey state (evidence: `src/components/common/state-machine/state-machine-executor.ts`)
- Journey executor → Passkey service: checks prompts (evidence: `src/components/common/state-machine/state-machine-executor.ts`)
- Email entry → Notifications: sends codes (evidence: `src/components/enter-email/enter-email-controller.ts`)
- Phone verification → Notifications: sends codes (evidence: `src/components/check-your-phone/check-your-phone-controller.ts`)
- Phone verification → MFA verification: verifies code (evidence: `src/components/check-your-phone/check-your-phone-controller.ts`)
- Authenticator setup → Notifications: sends codes (evidence: `src/components/setup-authenticator-app/setup-authenticator-app-controller.ts`)
- Authenticator setup → MFA verification: verifies code (evidence: `src/components/setup-authenticator-app/setup-authenticator-app-controller.ts`)
- Authenticator code → MFA verification: verifies code (evidence: `src/components/enter-authenticator-app-code/enter-authenticator-app-code-controller.ts`)
- Passkey journeys → Passkey service: uses passkeys
- Identity callbacks → Account recovery: handles recovery
- MFA reset → Identity callbacks: continues identity flow
- Contact support → Page templates: renders pages (evidence: `src/components/contact-us/contact-us-controller.ts`)
- OIDC authorize → Authentication API: requests authorization
- Notifications → Notification service: delivers messages
- Orchestration stub → Express app: initiates OIDC flow