# sphereon-opensource/ssi-sdk architecture

> Architecture diagram of the GitHub repository sphereon-opensource/ssi-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sphereon-opensource/ssi-sdk
- Repository: https://github.com/sphereon-opensource/ssi-sdk

## Overview

##### Project type and purpose
- This is a TypeScript monorepo (managed with Lerna/pnpm/turbo) providing a Self-Sovereign Identity SDK.
- It delivers modular “plugins” for Veramo-style agents: core utilities (ssi-sdk-core, ssi-types), persistence (data-store, kv-store), domain features (OID4VCI, SIOPv2/OID4VP, Presentation Exchange, Contact Manager, Issuance Branding, QR-Code generation, Well-known DIDs, MS Entra support, etc.), plus standalone REST-API “microservices” and a CLI.

##### File structure
- Root: configuration (tsconfig.*, lerna.json, turbo.json, CI workflows), scripts, build/test configs.
- packages/: dozens of sub-packages, each with its own README, src/, tests, schema, agent.yml.
- Categories (implied by README):
– Generic Core: ssi-types, ssi-sdk-core
– Persistence: data-store (TypeORM), kv-store
– Domain Plugins: presentation-exchange, oid4vci-issuer, siopv2-* , wellknown-did-*, contact-manager, issuance-branding, qr-code-generator, etc.
– REST API Layers: *-rest-api packages (oid4vci-issuer-rest-api, siopv2-rp-rest-api, contact-manager-rest-api, pd-manager-rest-api, public-key-hosting, etc.)
– CLI: packages/dev/bin and src

##### Extract insights from the README
- Confirms plugin categories and their intended usage contexts (issuer, holder, verifier, Relying Party, webapp, mobile).
- Notes that most plugins plug into an “Agent” runtime (NodeJS or React-Native), with some also exposing a REST API (Express).
- Underlying persistence uses TypeORM (data-store) or key-value abstractions (kv-store).

##### Elements
– Plugin → Core (integration)
– REST API → Plugin → Persistence → External Resolver
– CLI → Core & Plugins
– Core libraries (e.g., blue)
– Domain plugins (green)
– Persistence (orange)
– REST API (purple)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Configuration and CI
    subgraph "Monorepo & CI/CD"
        direction TB
        Config["Monorepo Config\n(lerna.json, turbo.json,\ntsconfig.*, workflows)"]:::config
    end

    %% Agent Runtime
    Agent["Agent Runtime\n(Veramo-style Agent)"]:::core

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        Core1["ssi-sdk-core"]:::core
        Core2["ssi-types"]:::core
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DS["TypeORM Data Store"]:::persistence
        KV["Key/Value Store"]:::persistence
    end

    %% Domain Plugins
    subgraph "Domain Plugins"
        direction TB
        PE["Presentation Exchange"]:::plugin
        OI["OID4VCI Issuer"]:::plugin
        OIS["OID4VCI Issuer Store"]:::plugin
        OH["OID4VCI Holder"]:::plugin
        SA["SIOPv2 OP-Auth"]:::plugin
        SR["SIOPv2 RP-Auth"]:::plugin
        CM["Contact Manager"]:::plugin
        IB["Issuance Branding"]:::plugin
        WI["Well-Known DID Issuer"]:::plugin
        WV["Well-Known DID Verifier"]:::plugin
        MA["Microsoft Authenticator"]:::plugin
        MR["MS Entra Request API"]:::plugin
        QR["QR-Code Generator"]:::plugin
    end

    %% REST API Services
    subgraph "REST API Services"
        direction TB
        API1["OID4VCI Issuer REST API"]:::api
        API2["SIOPv2 RP REST API"]:::api
        API3["Contact Manager REST API"]:::api
        API4["PD Manager REST API"]:::api
        API5["Public Key Hosting API"]:::api
        API6["VC Status List Issuer REST API"]:::api
        API7["W3C VC API Server"]:::api
        API8["Universal Resolver Registrar API"]:::api
    end

    %% CLI Tool
    CLI["CLI Tool\n(sphereon)"]:::cli

    %% External Services
    subgraph "External Services"
        direction TB
        Ext1["DID Resolver Endpoint"]:::external
        Ext2["OpenID/OAuth Endpoints"]:::external
        ExtDB["PostgreSQL / SQLite"]:::external
    end

    %% Connections - Config
    Config -->|configures| Agent
    Config -->|build/test| CLI

    %% Agent integrations
    Core1 --> Agent
    Core2 --> Agent
    DS --> Agent
    KV --> Agent

    %% Plugins loaded into Agent
    PE --> Agent
    OI --> Agent
    OIS --> Agent
    OH --> Agent
    SA --> Agent
    SR --> Agent
    CM --> Agent
    IB --> Agent
    WI --> Agent
    WV --> Agent
    MA --> Agent
    MR --> Agent
    QR --> Agent

    %% CLI uses Agent & Plugins
    CLI --> Agent
    CLI --> PE
    CLI --> OI

    %% REST API mapping
    API1 -->|routes to| OI
    API1 --> DS
    API1 --> Ext1

    API2 -->|routes to| SR
    API2 --> DS
    API2 --> Ext2

    API3 -->|routes to| CM
    API3 --> KV
    API4 -->|routes to| CM
    API4 --> KV

    API5 -->|routes to| WI
    API6 -->|routes to| OIS
    API7 -->|routes to| PE
    API7 --> DS

    API8 -->|manages resolver| Ext1

    %% External DB
    DS --> ExtDB
    KV --> ExtDB

    %% Click Events
    click Core1 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/ssi-sdk-core"
    click Core2 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/ssi-types"
    click DS "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/data-store"
    click KV "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/kv-store"
    click PE "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/presentation-exchange"
    click OI "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/oid4vci-issuer"
    click OIS "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/oid4vci-issuer-store"
    click OH "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/oid4vci-holder"
    click SA "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/siopv2-oid4vp-op-auth"
    click SR "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/siopv2-oid4vp-rp-auth"
    click CM "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/contact-manager"
    click IB "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/issuance-branding"
    click WI "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/wellknown-did-issuer"
    click WV "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/wellknown-did-verifier"
    click MA "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/ms-authenticator"
    click MR "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/ms-request-api"
    click QR "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/qr-code-generator"
    click API1 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/oid4vci-issuer-rest-api"
    click API2 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/siopv2-oid4vp-rp-rest-api"
    click API3 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/contact-manager-rest-api"
    click API4 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/pd-manager-rest-api"
    click API5 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/public-key-hosting"
    click API6 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/vc-status-list-issuer-rest-api"
    click API7 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/w3c-vc-api"
    click API8 "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/uni-resolver-registrar-api"
    click CLI "https://github.com/sphereon-opensource/ssi-sdk/tree/develop/packages/dev/bin"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,color:#1B4F72
    classDef persistence fill:#FDEBD0,stroke:#CA6F1E,color:#6E2C00
    classDef plugin fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef api fill:#E8DAEF,stroke:#8E44AD,color:#4A235A
    classDef cli fill:#FADBD8,stroke:#C0392B,color:#641E16
    classDef config fill:#F2F3F4,stroke:#7B7D7D,color:#424949
    classDef external stroke-dasharray: 5 5,stroke:#7B7D7D,color:#424949
```
