# govuk-one-login/mobile-wallet-example-credential-issuer architecture

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

- Interactive diagram: https://gitdiagram.com/govuk-one-login/mobile-wallet-example-credential-issuer
- Repository: https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer

## Overview

This repository is a set of GOV.UK Wallet example-issuer tools. The principal document-builder workflow is to select an app and document type, enter credential data, optionally upload a portrait, persist a test document, then redirect to its credential offer for use by an issuer. The tree also includes authentication and credential-lifecycle endpoints, a document-signing certificate issuer, and a test harness serving JWKS. Controller excerpts support the shown storage and upload calls; several other subsystem relationships are documented by the README or remain unverified in the sampled sources.

Main entry points: [`document-builder/src/services/databaseService.ts`](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/services/databaseService.ts) (Document records), [`document-builder/src/services/s3Service.ts`](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/services/s3Service.ts) (Portrait storage), [`test-harness/src/app.ts`](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/test-harness/src/app.ts) (Test harness), [`document-signing-certificate-issuer/src/issueDocumentSigningCertificate.ts`](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-signing-certificate-issuer/src/issueDocumentSigningCertificate.ts) (Certificate issuer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_builder["Document builder"]
  node_appselect["App selection<br/>[controller.ts]"]
  node_docselect["Document selection<br/>[controller.ts]"]
  node_docforms["Credential forms"]
  node_driving["Driving licences<br/>[controller.ts]"]
  node_veteran["Veteran card<br/>[controller.ts]"]
  node_simple["Simple document<br/>[controller.ts]"]
  node_dbs["DBS document<br/>[controller.ts]"]
  node_nino["NINO document<br/>[controller.ts]"]
  node_dvs["DVS licence<br/>[controller.ts]"]
  node_documentview["Document retrieval<br/>[controller.ts]"]
  node_database[("Document records<br/>[databaseService.ts]")]
  node_photos[("Portrait storage<br/>[s3Service.ts]")]
  node_journey["DVS journey<br/>[controller.ts]"]
  node_appstart["DVS start<br/>[controller.ts]"]
end

subgraph group_security["Issuer security"]
  node_auth["Auth callbacks<br/>[controller.ts]"]
  node_proof["Proof JWT<br/>[proofJwt.ts]"]
  node_refresh["Token refresh<br/>[controller.ts]"]
  node_revoke["Credential revocation<br/>[controller.ts]"]
  node_logout["Logout<br/>[controller.ts]"]
  node_signissuer["Certificate issuer"]
  node_acmpca["AWS PCA adapter<br/>[acmPcaAdapter.ts]"]
  node_s3cert["Certificate S3 adapter<br/>[s3Adapter.ts]"]
  node_ca["Private platform CA"]
end

subgraph group_validation["Issuer validation"]
  node_harness["Test harness<br/>[app.ts]"]
  node_keypair["Harness key pair"]
  node_jwks["JWKS response"]
end

node_user(("Builder user"))
node_issuer(("Credential issuer"))
node_testuser(("Harness client"))

node_user -.->|"selects app"| node_appselect
node_user -.->|"chooses document"| node_docselect
node_docforms -.->|"stores records"| node_database
node_driving -->|"saves record"| node_database
node_driving -->|"uploads portrait"| node_photos
node_veteran -->|"saves record"| node_database
node_veteran -->|"uploads portrait"| node_photos
node_simple -->|"saves record"| node_database
node_simple -->|"uploads portrait"| node_photos
node_dbs -->|"saves record"| node_database
node_nino -->|"saves record"| node_database
node_dvs -->|"saves record"| node_database
node_dvs -->|"uploads portrait"| node_photos
node_documentview -->|"reads record"| node_database
node_documentview -->|"loads portrait"| node_photos
node_user -.->|"returns from auth"| node_auth
node_user -.->|"requests proof"| node_proof
node_user -.->|"refreshes token"| node_refresh
node_user -.->|"requests revocation"| node_revoke
node_user -.->|"logs out"| node_logout
node_signissuer -->|"issues certificate"| node_acmpca
node_signissuer -->|"stores certificate"| node_s3cert
node_testuser -.->|"requests JWKS"| node_harness
node_harness -->|"initializes key"| node_keypair
node_harness -->|"serves key set"| node_jwks
node_issuer -.->|"uses test documents"| node_database
node_ca -.->|"supports signing"| node_signissuer

click node_appselect "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/appSelector/controller.ts"
click node_docselect "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/documentSelector/controller.ts"
click node_docforms "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/tree/main/document-builder/src"
click node_driving "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/drivingLicenceBuilder/controller.ts"
click node_veteran "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/veteranCardDocumentBuilder/controller.ts"
click node_simple "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/simpleDocumentBuilder/controller.ts"
click node_dbs "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dbsDocumentBuilder/controller.ts"
click node_nino "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/ninoDocumentBuilder/controller.ts"
click node_dvs "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dvsDrivingLicenceBuilder/controller.ts"
click node_documentview "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/document/controller.ts"
click node_database "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/services/databaseService.ts"
click node_photos "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/services/s3Service.ts"
click node_journey "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dvsJourneySelector/controller.ts"
click node_appstart "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dvsStart/controller.ts"
click node_auth "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/returnFromAuth/controller.ts"
click node_proof "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/proofJwt/proofJwt.ts"
click node_refresh "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/refresh/controller.ts"
click node_revoke "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/revoke/controller.ts"
click node_logout "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/logout/controller.ts"
click node_signissuer "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-signing-certificate-issuer/src/issueDocumentSigningCertificate.ts"
click node_acmpca "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-signing-certificate-issuer/src/adapters/aws/acmPcaAdapter.ts"
click node_s3cert "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-signing-certificate-issuer/src/adapters/aws/s3Adapter.ts"
click node_harness "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/test-harness/src/app.ts"
click node_keypair "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/test-harness/src/initialiseKeyPair.ts"
click node_jwks "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/test-harness/src/buildJwksResponse.ts"
click node_ca "https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/tree/main/platform-ca"

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_appselect,node_docselect,node_docforms,node_driving,node_veteran,node_simple,node_dbs,node_nino,node_dvs,node_documentview,node_database,node_photos,node_journey,node_appstart,node_user,node_testuser toneBlue
class node_auth,node_proof,node_refresh,node_revoke,node_logout,node_signissuer,node_acmpca,node_s3cert,node_ca toneAmber
class node_harness,node_keypair,node_jwks toneMint
class node_issuer toneIndigo
```

## Components

### Document builder

- [App selection](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/appSelector/controller.ts): `document-builder/src/appSelector/controller.ts`
- [Document selection](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/documentSelector/controller.ts): `document-builder/src/documentSelector/controller.ts`
- [Credential forms](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/tree/main/document-builder/src): `document-builder/src`
- [Driving licences](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/drivingLicenceBuilder/controller.ts): `document-builder/src/drivingLicenceBuilder/controller.ts`
- [Veteran card](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/veteranCardDocumentBuilder/controller.ts): `document-builder/src/veteranCardDocumentBuilder/controller.ts`
- [Simple document](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/simpleDocumentBuilder/controller.ts): `document-builder/src/simpleDocumentBuilder/controller.ts`
- [DBS document](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dbsDocumentBuilder/controller.ts): `document-builder/src/dbsDocumentBuilder/controller.ts`
- [NINO document](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/ninoDocumentBuilder/controller.ts): `document-builder/src/ninoDocumentBuilder/controller.ts`
- [DVS licence](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dvsDrivingLicenceBuilder/controller.ts): `document-builder/src/dvsDrivingLicenceBuilder/controller.ts`
- [Document retrieval](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/document/controller.ts): `document-builder/src/document/controller.ts`
- [Document records](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/services/databaseService.ts): `document-builder/src/services/databaseService.ts`
- [Portrait storage](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/services/s3Service.ts): `document-builder/src/services/s3Service.ts`
- [DVS journey](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dvsJourneySelector/controller.ts): `document-builder/src/dvsJourneySelector/controller.ts`
- [DVS start](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/dvsStart/controller.ts): `document-builder/src/dvsStart/controller.ts`

### Issuer security

- [Auth callbacks](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/returnFromAuth/controller.ts): `document-builder/src/returnFromAuth/controller.ts`
- [Proof JWT](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/proofJwt/proofJwt.ts): `document-builder/src/proofJwt/proofJwt.ts`
- [Token refresh](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/refresh/controller.ts): `document-builder/src/refresh/controller.ts`
- [Credential revocation](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/revoke/controller.ts): `document-builder/src/revoke/controller.ts`
- [Logout](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-builder/src/logout/controller.ts): `document-builder/src/logout/controller.ts`
- [Certificate issuer](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-signing-certificate-issuer/src/issueDocumentSigningCertificate.ts): `document-signing-certificate-issuer/src/issueDocumentSigningCertificate.ts`
- [AWS PCA adapter](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-signing-certificate-issuer/src/adapters/aws/acmPcaAdapter.ts): `document-signing-certificate-issuer/src/adapters/aws/acmPcaAdapter.ts`
- [Certificate S3 adapter](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/document-signing-certificate-issuer/src/adapters/aws/s3Adapter.ts): `document-signing-certificate-issuer/src/adapters/aws/s3Adapter.ts`
- [Private platform CA](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/tree/main/platform-ca): `platform-ca`

### Issuer validation

- [Test harness](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/test-harness/src/app.ts): `test-harness/src/app.ts`
- [Harness key pair](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/test-harness/src/initialiseKeyPair.ts): `test-harness/src/initialiseKeyPair.ts`
- [JWKS response](https://github.com/govuk-one-login/mobile-wallet-example-credential-issuer/blob/main/test-harness/src/buildJwksResponse.ts): `test-harness/src/buildJwksResponse.ts`

### Other components

- **Builder user**
- **Credential issuer**
- **Harness client**

## Connections

- Builder user → App selection: selects app
- Builder user → Document selection: chooses document
- Credential forms → Document records: stores records (evidence: `document-builder/src/drivingLicenceBuilder/controller.ts`)
- Driving licences → Document records: saves record (evidence: `document-builder/src/drivingLicenceBuilder/controller.ts`)
- Driving licences → Portrait storage: uploads portrait (evidence: `document-builder/src/drivingLicenceBuilder/controller.ts`)
- Veteran card → Document records: saves record (evidence: `document-builder/src/veteranCardDocumentBuilder/controller.ts`)
- Veteran card → Portrait storage: uploads portrait (evidence: `document-builder/src/veteranCardDocumentBuilder/controller.ts`)
- Simple document → Document records: saves record (evidence: `document-builder/src/simpleDocumentBuilder/controller.ts`)
- Simple document → Portrait storage: uploads portrait (evidence: `document-builder/src/simpleDocumentBuilder/controller.ts`)
- DBS document → Document records: saves record (evidence: `document-builder/src/dbsDocumentBuilder/controller.ts`)
- NINO document → Document records: saves record (evidence: `document-builder/src/ninoDocumentBuilder/controller.ts`)
- DVS licence → Document records: saves record (evidence: `document-builder/src/dvsDrivingLicenceBuilder/controller.ts`)
- DVS licence → Portrait storage: uploads portrait (evidence: `document-builder/src/dvsDrivingLicenceBuilder/controller.ts`)
- Document retrieval → Document records: reads record (evidence: `document-builder/src/document/controller.ts`)
- Document retrieval → Portrait storage: loads portrait (evidence: `document-builder/src/document/controller.ts`)
- Builder user → Auth callbacks: returns from auth
- Builder user → Proof JWT: requests proof
- Builder user → Token refresh: refreshes token
- Builder user → Credential revocation: requests revocation
- Builder user → Logout: logs out
- Certificate issuer → AWS PCA adapter: issues certificate (evidence: `document-signing-certificate-issuer/src/issueDocumentSigningCertificate.ts`)
- Certificate issuer → Certificate S3 adapter: stores certificate (evidence: `document-signing-certificate-issuer/src/issueDocumentSigningCertificate.ts`)
- Harness client → Test harness: requests JWKS
- Test harness → Harness key pair: initializes key (evidence: `test-harness/src/app.ts`)
- Test harness → JWKS response: serves key set (evidence: `test-harness/src/app.ts`)
- Credential issuer → Document records: uses test documents
- Private platform CA → Certificate issuer: supports signing
