# sunet/vc architecture

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

- Interactive diagram: https://gitdiagram.com/sunet/vc
- Repository: https://github.com/sunet/vc

## Overview

VC is a Go microservices platform for issuing and verifying digital credentials. A wallet requests issuance through the API Gateway, which handles authorization and consent and delegates signing to the Issuer; the Registry manages credential status lists. For verification, a relying party starts an OIDC flow with the Verifier, which requests a wallet presentation through OpenID4VP and returns the verification outcome. The README documents these principal flows and optional SAML/OIDC identity-provider paths; sampled source confirms service wiring, but not every runtime call in unsampled modules.

Main entry points: [`internal/apigw/apiv1/handlers_oauth.go`](https://github.com/sunet/vc/blob/main/internal/apigw/apiv1/handlers_oauth.go) (Gateway API), [`pkg/openid4vp`](https://github.com/sunet/vc/tree/main/pkg/openid4vp) (OpenID4VP), [`internal/verifier/apiv1`](https://github.com/sunet/vc/tree/main/internal/verifier/apiv1) (Verifier API), [`internal/issuer/grpcserver`](https://github.com/sunet/vc/tree/main/internal/issuer/grpcserver) (Issuer gRPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_issuance["Credential issuance"]
  node_apigw_api["Gateway API<br/>[handlers_oauth.go]"]
  node_issuance_challenge["Issuance challenge"]
  node_issuer_api["Issuer API<br/>[client.go]"]
  node_issuer_grpc["Issuer gRPC"]
end

subgraph group_verification["Credential verification"]
  node_verifier_http["Verifier HTTP"]
  node_verifier_api["Verifier API"]
  node_openid4vp["OpenID4VP"]
  node_mdoc_verify["Mdoc verification"]
  node_sdjwt_verify["SD-JWT verification"]
  node_vc20_verify["VC 2.0 verification<br/>[vc20_handler.go]"]
  node_oidc_provider["OIDC provider<br/>[handler_oauth.go]"]
end

subgraph group_services["Platform services"]
  node_apigw_http["Gateway HTTP<br/>[service.go]"]
  node_apigw_db[("Gateway datastore")]
  node_registry_api["Registry API"]
  node_status_issuer["Status-list issuer<br/>[service.go]"]
  node_registry_db[("Registry database")]
end

subgraph group_identity["Identity integrations"]
  node_auth_providers["Auth providers"]
end

node_wallet(("Wallet"))
node_relying_party(("Relying party"))
node_external_idp(("External IdP"))

node_wallet -->|"requests issuance"| node_apigw_http
node_apigw_http -->|"routes requests"| node_apigw_api
node_apigw_api -->|"delegates signing"| node_issuer_grpc
node_issuer_grpc -.->|"serves issuance"| node_issuer_api
node_apigw_api -->|"uses status service"| node_registry_api
node_apigw_api -->|"looks up documents"| node_apigw_db
node_apigw_api -.->|"handles challenge"| node_issuance_challenge
node_external_idp -->|"authenticates user"| node_auth_providers
node_apigw_api -->|"selects provider"| node_auth_providers
node_registry_api -.->|"issues status lists"| node_status_issuer
node_status_issuer -->|"reads and writes"| node_registry_db
node_relying_party -->|"starts OIDC flow"| node_verifier_http
node_verifier_http -->|"routes verification"| node_verifier_api
node_verifier_api -->|"handles OIDC"| node_oidc_provider
node_oidc_provider -->|"requests presentation"| node_wallet
node_wallet -->|"submits presentation"| node_openid4vp
node_verifier_api -.->|"verifies presentation"| node_openid4vp
node_openid4vp -.->|"handles mdoc"| node_mdoc_verify
node_openid4vp -.->|"handles SD-JWT"| node_sdjwt_verify
node_openid4vp -.->|"handles VC 2.0"| node_vc20_verify

click node_apigw_http "https://github.com/sunet/vc/blob/main/internal/apigw/httpserver/service.go"
click node_apigw_api "https://github.com/sunet/vc/blob/main/internal/apigw/apiv1/handlers_oauth.go"
click node_issuance_challenge "https://github.com/sunet/vc/blob/main/internal/apigw/apiv1/handlers_oauth_challenge.go"
click node_auth_providers "https://github.com/sunet/vc/tree/main/internal/apigw/auth_providers"
click node_apigw_db "https://github.com/sunet/vc/tree/main/internal/apigw/db"
click node_issuer_api "https://github.com/sunet/vc/blob/main/internal/issuer/apiv1/client.go"
click node_issuer_grpc "https://github.com/sunet/vc/tree/main/internal/issuer/grpcserver"
click node_registry_api "https://github.com/sunet/vc/blob/main/internal/registry/apiv1/handlers_token_status_list.go"
click node_status_issuer "https://github.com/sunet/vc/blob/main/internal/registry/tokenstatuslistissuer/service.go"
click node_registry_db "https://github.com/sunet/vc/tree/main/internal/registry/db"
click node_verifier_http "https://github.com/sunet/vc/blob/main/internal/verifier/httpserver/verification_routes.go"
click node_verifier_api "https://github.com/sunet/vc/tree/main/internal/verifier/apiv1"
click node_openid4vp "https://github.com/sunet/vc/tree/main/pkg/openid4vp"
click node_mdoc_verify "https://github.com/sunet/vc/blob/main/pkg/mdoc/openid4vp_handler.go"
click node_sdjwt_verify "https://github.com/sunet/vc/blob/main/pkg/sdjwtvc/openid4vp_handler.go"
click node_vc20_verify "https://github.com/sunet/vc/blob/main/pkg/openid4vp/vc20_handler.go"
click node_oidc_provider "https://github.com/sunet/vc/blob/main/internal/verifier/apiv1/handler_oauth.go"

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_apigw_api,node_issuance_challenge,node_issuer_api,node_issuer_grpc toneBlue
class node_verifier_http,node_verifier_api,node_openid4vp,node_mdoc_verify,node_sdjwt_verify,node_vc20_verify,node_oidc_provider toneAmber
class node_apigw_http,node_apigw_db,node_registry_api,node_status_issuer,node_registry_db toneMint
class node_auth_providers toneRose
class node_wallet,node_relying_party,node_external_idp toneIndigo
```

## Components

### Credential issuance

- [Gateway API](https://github.com/sunet/vc/blob/main/internal/apigw/apiv1/handlers_oauth.go): `internal/apigw/apiv1/handlers_oauth.go`
- [Issuance challenge](https://github.com/sunet/vc/blob/main/internal/apigw/apiv1/handlers_oauth_challenge.go): `internal/apigw/apiv1/handlers_oauth_challenge.go`
- [Issuer API](https://github.com/sunet/vc/blob/main/internal/issuer/apiv1/client.go): `internal/issuer/apiv1/client.go`
- [Issuer gRPC](https://github.com/sunet/vc/tree/main/internal/issuer/grpcserver): `internal/issuer/grpcserver`

### Credential verification

- [Verifier HTTP](https://github.com/sunet/vc/blob/main/internal/verifier/httpserver/verification_routes.go): `internal/verifier/httpserver/verification_routes.go`
- [Verifier API](https://github.com/sunet/vc/tree/main/internal/verifier/apiv1): `internal/verifier/apiv1`
- [OpenID4VP](https://github.com/sunet/vc/tree/main/pkg/openid4vp): `pkg/openid4vp`
- [Mdoc verification](https://github.com/sunet/vc/blob/main/pkg/mdoc/openid4vp_handler.go): `pkg/mdoc/openid4vp_handler.go`
- [SD-JWT verification](https://github.com/sunet/vc/blob/main/pkg/sdjwtvc/openid4vp_handler.go): `pkg/sdjwtvc/openid4vp_handler.go`
- [VC 2.0 verification](https://github.com/sunet/vc/blob/main/pkg/openid4vp/vc20_handler.go): `pkg/openid4vp/vc20_handler.go`
- [OIDC provider](https://github.com/sunet/vc/blob/main/internal/verifier/apiv1/handler_oauth.go): `internal/verifier/apiv1/handler_oauth.go`

### Platform services

- [Gateway HTTP](https://github.com/sunet/vc/blob/main/internal/apigw/httpserver/service.go): `internal/apigw/httpserver/service.go`
- [Gateway datastore](https://github.com/sunet/vc/tree/main/internal/apigw/db): `internal/apigw/db`
- [Registry API](https://github.com/sunet/vc/blob/main/internal/registry/apiv1/handlers_token_status_list.go): `internal/registry/apiv1/handlers_token_status_list.go`
- [Status-list issuer](https://github.com/sunet/vc/blob/main/internal/registry/tokenstatuslistissuer/service.go): `internal/registry/tokenstatuslistissuer/service.go`
- [Registry database](https://github.com/sunet/vc/tree/main/internal/registry/db): `internal/registry/db`

### Identity integrations

- [Auth providers](https://github.com/sunet/vc/tree/main/internal/apigw/auth_providers): `internal/apigw/auth_providers`

### Other components

- **Wallet**
- **Relying party**
- **External IdP**

## Connections

- Wallet → Gateway HTTP: requests issuance (evidence: `README.md`)
- Gateway HTTP → Gateway API: routes requests (evidence: `internal/apigw/httpserver/service.go`)
- Gateway API → Issuer gRPC: delegates signing (evidence: `README.md`)
- Issuer gRPC → Issuer API: serves issuance
- Gateway API → Registry API: uses status service (evidence: `README.md`)
- Gateway API → Gateway datastore: looks up documents (evidence: `README.md`)
- Gateway API → Issuance challenge: handles challenge
- External IdP → Auth providers: authenticates user (evidence: `README.md`)
- Gateway API → Auth providers: selects provider
- Registry API → Status-list issuer: issues status lists
- Status-list issuer → Registry database: reads and writes (evidence: `internal/registry/tokenstatuslistissuer/service.go`)
- Relying party → Verifier HTTP: starts OIDC flow (evidence: `README.md`)
- Verifier HTTP → Verifier API: routes verification (evidence: `internal/verifier/httpserver/verification_routes.go`)
- Verifier API → OIDC provider: handles OIDC (evidence: `README.md`)
- OIDC provider → Wallet: requests presentation (evidence: `README.md`)
- Wallet → OpenID4VP: submits presentation (evidence: `README.md`)
- Verifier API → OpenID4VP: verifies presentation
- OpenID4VP → Mdoc verification: handles mdoc
- OpenID4VP → SD-JWT verification: handles SD-JWT
- OpenID4VP → VC 2.0 verification: handles VC 2.0
