# harmonizedx/open-residency architecture

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

- Interactive diagram: https://gitdiagram.com/harmonizedx/open-residency
- Repository: https://github.com/harmonizedx/open-residency

## Overview

OpenResidency is jurisdiction-owned residency verification and trust infrastructure. Its main workflow is operator-led identity verification, policy-gated residency issuance, then credential delivery and cross-sector use. The graph also retains offline access, OpenID login, consent and governance, lifecycle/audit, and operator administration. Edges follow the documented workflow and sampled controller calls; several unsampled subsystems are represented by their supported source paths without speculative internal wiring.

Main entry points: [`src/prisma/prisma.service.ts`](https://github.com/harmonizedx/open-residency/blob/main/src/prisma/prisma.service.ts) (Resident store), [`src/core/residency/residency-service.ts`](https://github.com/harmonizedx/open-residency/blob/main/src/core/residency/residency-service.ts) (Residency service), [`src/residency/residency.controller.ts`](https://github.com/harmonizedx/open-residency/blob/main/src/residency/residency.controller.ts) (Residency API), [`src/oid4vci/oid4vci.controller.ts`](https://github.com/harmonizedx/open-residency/blob/main/src/oid4vci/oid4vci.controller.ts) (OpenID4VCI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_enrollment["Enrollment and residency"]
  node_identity_api["Identity API"]
  node_residency_api["Residency API"]
  node_residency["Residency service"]
  node_foundational["Identity sources<br/>[registry.ts]"]
  node_adapters{{"Source adapters"}}
  node_credential_store[("Resident store<br/>[prisma.service.ts]")]
end

subgraph group_credentials["Credential exchange"]
  node_oid4vci_api["OpenID4VCI API"]
  node_oid4vci["Credential issuance<br/>[oid4vci-service.ts]"]
  node_oid4vp_api["OpenID4VP API"]
  node_oid4vp["Presentation verification<br/>[oid4vp-service.ts]"]
  node_vcapi["VC verification API"]
end

subgraph group_access["Access and inclusion"]
  node_offline_api["Offline access API"]
  node_sso["Sector SSO<br/>[oidc.provider.ts]"]
  node_interaction["Login interaction"]
  node_webauthn["WebAuthn service"]
  node_ussd["USSD and SMS<br/>[ussd.ts]"]
end

subgraph group_governance["Governance and assurance"]
  node_consent["Consent management"]
  node_assurance["Assurance registry<br/>[registry.ts]"]
  node_audit["Audit trail<br/>[audit-log.ts]"]
  node_privacy["Privacy controls<br/>[erasure.ts]"]
end

subgraph group_operations["Deployment operations"]
  node_operator_api["Operator administration"]
  node_platform["Platform services"]
  node_upstream["Upstream OIDC"]
  node_federation["Federation trust<br/>[federated.ts]"]
end

node_citizen(("Citizen"))
node_operator(("Registrar"))
node_national_id["National ID source"]
node_wallet(("Credential wallet"))
node_relying_party(("Sector service"))

node_operator -->|"starts verification"| node_identity_api
node_identity_api -->|"requests verification"| node_residency
node_residency -->|"resolves provider"| node_foundational
node_foundational -->|"selects adapter"| node_adapters
node_adapters -->|"checks identity"| node_national_id
node_national_id -->|"returns result"| node_adapters
node_operator -->|"requests issuance"| node_residency_api
node_residency_api -->|"issues credential"| node_residency
node_residency -->|"checks assurance"| node_assurance
node_residency -->|"records resident"| node_credential_store
node_residency_api -->|"reads resident"| node_credential_store
node_wallet -->|"requests credential"| node_oid4vci_api
node_oid4vci_api -->|"handles exchange"| node_oid4vci
node_oid4vci -->|"reads residency"| node_credential_store
node_oid4vci_api -->|"returns credential"| node_wallet
node_wallet -->|"submits presentation"| node_oid4vp_api
node_oid4vp_api -->|"verifies presentation"| node_oid4vp
node_relying_party -->|"requests verification"| node_oid4vp_api
node_relying_party -->|"verifies credential"| node_vcapi
node_citizen -->|"uses offline access"| node_offline_api
node_offline_api -->|"handles USSD"| node_ussd
node_offline_api -->|"looks up resident"| node_credential_store
node_relying_party -->|"starts login"| node_sso
node_sso -->|"dispatches interaction"| node_interaction
node_interaction -->|"verifies factor"| node_webauthn
node_interaction -->|"records login"| node_audit
node_operator -->|"manages accounts"| node_operator_api
node_operator_api -->|"uses operator services"| node_platform
node_residency_api -->|"records lifecycle"| node_audit
node_consent -->|"checks resident"| node_credential_store
node_consent -->|"records governance"| node_audit
node_privacy -->|"erases data"| node_credential_store
node_upstream -->|"uses identity client"| node_platform
node_platform -.->|"provides federation"| node_federation
node_ussd -->|"sends status"| node_citizen

click node_identity_api "https://github.com/harmonizedx/open-residency/blob/main/src/identity/identity.controller.ts"
click node_residency_api "https://github.com/harmonizedx/open-residency/blob/main/src/residency/residency.controller.ts"
click node_residency "https://github.com/harmonizedx/open-residency/blob/main/src/core/residency/residency-service.ts"
click node_foundational "https://github.com/harmonizedx/open-residency/blob/main/src/core/foundational/registry.ts"
click node_adapters "https://github.com/harmonizedx/open-residency/tree/main/src/core/foundational/adapters"
click node_credential_store "https://github.com/harmonizedx/open-residency/blob/main/src/prisma/prisma.service.ts"
click node_oid4vci_api "https://github.com/harmonizedx/open-residency/blob/main/src/oid4vci/oid4vci.controller.ts"
click node_oid4vci "https://github.com/harmonizedx/open-residency/blob/main/src/core/oid4vci/oid4vci-service.ts"
click node_oid4vp_api "https://github.com/harmonizedx/open-residency/blob/main/src/oid4vp/oid4vp.controller.ts"
click node_oid4vp "https://github.com/harmonizedx/open-residency/blob/main/src/core/oid4vp/oid4vp-service.ts"
click node_vcapi "https://github.com/harmonizedx/open-residency/blob/main/src/vcapi/vcapi.controller.ts"
click node_offline_api "https://github.com/harmonizedx/open-residency/blob/main/src/offline/offline.controller.ts"
click node_sso "https://github.com/harmonizedx/open-residency/blob/main/src/sso/oidc.provider.ts"
click node_interaction "https://github.com/harmonizedx/open-residency/blob/main/src/sso/interaction.controller.ts"
click node_webauthn "https://github.com/harmonizedx/open-residency/blob/main/src/core/sso/webauthn-service.ts"
click node_ussd "https://github.com/harmonizedx/open-residency/blob/main/src/core/offline/ussd.ts"
click node_consent "https://github.com/harmonizedx/open-residency/blob/main/src/consent/consent.controller.ts"
click node_assurance "https://github.com/harmonizedx/open-residency/blob/main/src/core/assurance/registry.ts"
click node_audit "https://github.com/harmonizedx/open-residency/blob/main/src/core/audit/audit-log.ts"
click node_privacy "https://github.com/harmonizedx/open-residency/blob/main/src/core/privacy/erasure.ts"
click node_operator_api "https://github.com/harmonizedx/open-residency/blob/main/src/operator/operator.controller.ts"
click node_platform "https://github.com/harmonizedx/open-residency/blob/main/src/platform/platform.service.ts"
click node_upstream "https://github.com/harmonizedx/open-residency/blob/main/src/upstream/upstream.controller.ts"
click node_federation "https://github.com/harmonizedx/open-residency/blob/main/src/core/operator/federated.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_identity_api,node_residency_api,node_residency,node_foundational,node_adapters,node_credential_store toneBlue
class node_oid4vci_api,node_oid4vci,node_oid4vp_api,node_oid4vp,node_vcapi toneAmber
class node_offline_api,node_sso,node_interaction,node_webauthn,node_ussd toneMint
class node_consent,node_assurance,node_audit,node_privacy toneRose
class node_operator_api,node_platform,node_upstream,node_federation,node_citizen,node_operator,node_national_id,node_wallet,node_relying_party toneIndigo
```

## Components

### Enrollment and residency

- [Identity API](https://github.com/harmonizedx/open-residency/blob/main/src/identity/identity.controller.ts): `src/identity/identity.controller.ts`
- [Residency API](https://github.com/harmonizedx/open-residency/blob/main/src/residency/residency.controller.ts): `src/residency/residency.controller.ts`
- [Residency service](https://github.com/harmonizedx/open-residency/blob/main/src/core/residency/residency-service.ts): `src/core/residency/residency-service.ts`
- [Identity sources](https://github.com/harmonizedx/open-residency/blob/main/src/core/foundational/registry.ts): `src/core/foundational/registry.ts`
- [Source adapters](https://github.com/harmonizedx/open-residency/tree/main/src/core/foundational/adapters): `src/core/foundational/adapters`
- [Resident store](https://github.com/harmonizedx/open-residency/blob/main/src/prisma/prisma.service.ts): `src/prisma/prisma.service.ts`

### Credential exchange

- [OpenID4VCI API](https://github.com/harmonizedx/open-residency/blob/main/src/oid4vci/oid4vci.controller.ts): `src/oid4vci/oid4vci.controller.ts`
- [Credential issuance](https://github.com/harmonizedx/open-residency/blob/main/src/core/oid4vci/oid4vci-service.ts): `src/core/oid4vci/oid4vci-service.ts`
- [OpenID4VP API](https://github.com/harmonizedx/open-residency/blob/main/src/oid4vp/oid4vp.controller.ts): `src/oid4vp/oid4vp.controller.ts`
- [Presentation verification](https://github.com/harmonizedx/open-residency/blob/main/src/core/oid4vp/oid4vp-service.ts): `src/core/oid4vp/oid4vp-service.ts`
- [VC verification API](https://github.com/harmonizedx/open-residency/blob/main/src/vcapi/vcapi.controller.ts): `src/vcapi/vcapi.controller.ts`

### Access and inclusion

- [Offline access API](https://github.com/harmonizedx/open-residency/blob/main/src/offline/offline.controller.ts): `src/offline/offline.controller.ts`
- [Sector SSO](https://github.com/harmonizedx/open-residency/blob/main/src/sso/oidc.provider.ts): `src/sso/oidc.provider.ts`
- [Login interaction](https://github.com/harmonizedx/open-residency/blob/main/src/sso/interaction.controller.ts): `src/sso/interaction.controller.ts`
- [WebAuthn service](https://github.com/harmonizedx/open-residency/blob/main/src/core/sso/webauthn-service.ts): `src/core/sso/webauthn-service.ts`
- [USSD and SMS](https://github.com/harmonizedx/open-residency/blob/main/src/core/offline/ussd.ts): `src/core/offline/ussd.ts`

### Governance and assurance

- [Consent management](https://github.com/harmonizedx/open-residency/blob/main/src/consent/consent.controller.ts): `src/consent/consent.controller.ts`
- [Assurance registry](https://github.com/harmonizedx/open-residency/blob/main/src/core/assurance/registry.ts): `src/core/assurance/registry.ts`
- [Audit trail](https://github.com/harmonizedx/open-residency/blob/main/src/core/audit/audit-log.ts): `src/core/audit/audit-log.ts`
- [Privacy controls](https://github.com/harmonizedx/open-residency/blob/main/src/core/privacy/erasure.ts): `src/core/privacy/erasure.ts`

### Deployment operations

- [Operator administration](https://github.com/harmonizedx/open-residency/blob/main/src/operator/operator.controller.ts): `src/operator/operator.controller.ts`
- [Platform services](https://github.com/harmonizedx/open-residency/blob/main/src/platform/platform.service.ts): `src/platform/platform.service.ts`
- [Upstream OIDC](https://github.com/harmonizedx/open-residency/blob/main/src/upstream/upstream.controller.ts): `src/upstream/upstream.controller.ts`
- [Federation trust](https://github.com/harmonizedx/open-residency/blob/main/src/core/operator/federated.ts): `src/core/operator/federated.ts`

### Other components

- **Citizen**
- **Registrar**
- **National ID source**
- **Credential wallet**
- **Sector service**

## Connections

- Registrar → Identity API: starts verification
- Identity API → Residency service: requests verification
- Residency service → Identity sources: resolves provider
- Identity sources → Source adapters: selects adapter
- Source adapters → National ID source: checks identity
- National ID source → Source adapters: returns result
- Registrar → Residency API: requests issuance
- Residency API → Residency service: issues credential
- Residency service → Assurance registry: checks assurance
- Residency service → Resident store: records resident
- Residency API → Resident store: reads resident
- Credential wallet → OpenID4VCI API: requests credential
- OpenID4VCI API → Credential issuance: handles exchange
- Credential issuance → Resident store: reads residency
- OpenID4VCI API → Credential wallet: returns credential
- Credential wallet → OpenID4VP API: submits presentation
- OpenID4VP API → Presentation verification: verifies presentation
- Sector service → OpenID4VP API: requests verification
- Sector service → VC verification API: verifies credential
- Citizen → Offline access API: uses offline access
- Offline access API → USSD and SMS: handles USSD
- Offline access API → Resident store: looks up resident
- Sector service → Sector SSO: starts login
- Sector SSO → Login interaction: dispatches interaction
- Login interaction → WebAuthn service: verifies factor
- Login interaction → Audit trail: records login
- Registrar → Operator administration: manages accounts
- Operator administration → Platform services: uses operator services
- Residency API → Audit trail: records lifecycle
- Consent management → Resident store: checks resident
- Consent management → Audit trail: records governance
- Privacy controls → Resident store: erases data
- Upstream OIDC → Platform services: uses identity client
- Platform services → Federation trust: provides federation
- USSD and SMS → Citizen: sends status