# walt-id/waltid-identity architecture

> Architecture diagram of the GitHub repository walt-id/waltid-identity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/walt-id/waltid-identity
- Repository: https://github.com/walt-id/waltid-identity

## Overview

##### Project type and purpose
- This is a monorepo for “Identity by walt.id”: a full-stack, multi-platform identity solution.
- It contains:
– Kotlin/Java and JavaScript libraries (crypto, DID, credentials, protocols, auth, permissions).
– REST microservices (Issuer API, Verifier API, Wallet API, Web3-login service).
– White-label applications (Web wallet, Portal, CLI, Android & iOS sample apps).
– Docker-compose configuration for local end-to-end deployment.

##### File structure
- Top-level directories:
– waltid-libraries/… – core SDK modules (crypto, did, credentials, sdJwt, openid4vc, authnz, permissions) organized by domain.
– waltid-services/… – REST service projects each with config/, src/, Dockerfile, k8s/.
– waltid-applications/… – front-end apps and the CLI under separate subfolders.
– docker-compose/ – orchestrates services & apps via Docker Compose.
- Each microservice in waltid-services follows a similar Ktor-based MVC/web plugin structure with config files, main entrypoint, controllers, services, persistence models and tests.
- The libraries are multi-module, multi-platform (commonMain, jvmMain, iosMain, jsMain, with tests).
- README and .github/workflows define CI/CD and releases.

##### Insights from README
- The README enumerates functional blocks:
– SDKs: Crypto, DID, W3C credentials, mdoc, OpenID4VC, SD-JWT, Auth/NZ, Permissions.
– REST APIs: Issuer, Verifier, Wallet.
– Apps: Web-wallet (nuxt/PWA), Portal (Next.js), CLI, Android & iOS test apps.

##### Main components
a. Multi-Platform Libraries (SDK layer)
– Crypto, DID, Credential parsers & signers, Protocol implementations.
b. REST Services (Backend layer)
– Issuer API
– Verifier API
– Wallet API
– (Optional) Web3-login microservice
c. Applications (Frontend & CLI)
– Waltid-CLI (Kotlin Multiplatform command-line tool)
– Waltid-Web-Portal (Next.js issuer/verifier UI)
– Waltid-Web-Wallet (Nuxt.js PWA)
– Mobile samples (Android, iOS)
d. Orchestration & Infrastructure
– Docker-Compose group, Caddy reverse‐proxy, Vault, databases (Postgres/MSSQL/SQLite options), configuration.
– Kubernetes manifests under each service’s k8s/ folder for prod/dev.

##### Relationships & interactions
- SDK libraries are dependencies of the microservices and apps.
- Frontends talk to their respective REST APIs (Wallet UI → Wallet API, Portal → Issuer & Verifier APIs).
- Issuer API uses Crypto & DID SDK to sign/issue credentials, persists state in DB.
- Verifier API fetches credential presentations, uses Credential & Policy SDKs.
- Wallet API orchestrates user accounts, stores credentials, interacts with DID resolver and key-management SDKs.
- CLI invokes underlying libraries directly and can call REST endpoints.
- docker-compose.yml wires all services + Vault + Caddy + DB into a local testbed.

##### Architectural patterns & principles
- Modular monorepo: clear separation by domain.
- Microservice pattern for backend APIs, each with its own database and config.
- MPP (Kotlin Multiplatform) for shared code across JVM, JS, iOS.
- MVC/web-plugin structure in Ktor-based services.
- Infrastructure as code: Docker Compose for local dev, Kubernetes manifests for cloud.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "SDK Libraries"
        Crypto["Crypto"]:::sdk
        DID["DID"]:::sdk
        DC["Digital Credentials"]:::sdk
        MDOC["mDOC Credentials"]:::sdk
        W3C["W3C Credentials"]:::sdk
        Policies["Verification Policies"]:::sdk
        Protocols["OpenID4VC Protocol"]:::sdk
        AuthNZ["Ktor AuthNZ"]:::sdk
        IDPKit["IDP Kit"]:::sdk
        Permissions["Permissions"]:::sdk
    end

    subgraph "Backend Services"
        IssuerAPI["Issuer API"]:::services
        VerifierAPI["Verifier API"]:::services
        WalletAPI["Wallet API"]:::services
        Web3Login["Web3-login Service"]:::services
    end

    subgraph "Applications"
        CLI["Waltid-CLI"]:::apps
        WebPortal["Web Portal"]:::apps
        WebWallet["Web Wallet"]:::apps
        Android["Android Sample App"]:::apps
        iOSCrypto["iOS Crypto Test App"]:::apps
        iOSOpenID["iOS OpenID4VC App"]:::apps
    end

    subgraph "Infrastructure"
        DockerCompose["Docker Compose"]:::infra
        Vault["Vault"]:::infra
        Caddy["Caddy"]:::infra
        DB["Databases (Postgres/MSSQL/SQLite)"]:::infra
    end

    %% SDK to Services
    Crypto -->|depends on| IssuerAPI
    DID -->|depends on| IssuerAPI
    DC -->|depends on| VerifierAPI
    Policies -->|depends on| VerifierAPI
    AuthNZ -->|depends on| WalletAPI
    Protocols -->|used by| Web3Login

    %% SDK to Applications
    IDPKit -->|embedded in| CLI
    Permissions -->|embedded in| WebWallet
    Protocols -->|used by| iOSOpenID

    %% Applications to Services
    WebWallet -->|HTTP/REST| WalletAPI
    WebPortal -->|HTTP/REST| IssuerAPI
    WebPortal -->|HTTP/REST| VerifierAPI
    CLI -->|CLI commands| IssuerAPI
    CLI -->|CLI commands| VerifierAPI
    CLI -->|CLI commands| WalletAPI

    %% Services to Infrastructure
    IssuerAPI -->|reads/writes| DB
    VerifierAPI -->|reads/writes| DB
    WalletAPI -->|reads/writes| DB
    Web3Login -->|stores config| Vault
    WalletAPI -->|services via| Caddy

    %% Orchestration
    DockerCompose --> IssuerAPI
    DockerCompose --> VerifierAPI
    DockerCompose --> WalletAPI
    DockerCompose --> Web3Login
    DockerCompose --> WebPortal
    DockerCompose --> WebWallet
    DockerCompose --> Vault
    DockerCompose --> Caddy
    DockerCompose --> DB

    %% Click Events
    click Crypto "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/crypto/waltid-crypto"
    click DID "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/did/waltid-did"
    click DC "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/credentials/waltid-digital-credentials"
    click MDOC "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/credentials/waltid-mdoc-credentials"
    click W3C "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/credentials/waltid-w3c-credentials"
    click Policies "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/credentials/waltid-verification-policies"
    click Protocols "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/protocols/waltid-openid4vc"
    click AuthNZ "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/auth/waltid-ktor-authnz"
    click IDPKit "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/auth/waltid-idpkit"
    click Permissions "https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/auth/waltid-permissions"
    click IssuerAPI "https://github.com/walt-id/waltid-identity/tree/main/waltid-services/waltid-issuer-api"
    click VerifierAPI "https://github.com/walt-id/waltid-identity/tree/main/waltid-services/waltid-verifier-api"
    click WalletAPI "https://github.com/walt-id/waltid-identity/tree/main/waltid-services/waltid-wallet-api"
    click Web3Login "https://github.com/walt-id/waltid-identity/tree/main/waltid-services/waltid-web3login-microservice"
    click CLI "https://github.com/walt-id/waltid-identity/tree/main/waltid-applications/waltid-cli"
    click WebPortal "https://github.com/walt-id/waltid-identity/tree/main/waltid-applications/waltid-web-portal"
    click WebWallet "https://github.com/walt-id/waltid-identity/tree/main/waltid-applications/waltid-web-wallet"
    click Android "https://github.com/walt-id/waltid-identity/tree/main/waltid-applications/waltid-android"
    click iOSCrypto "https://github.com/walt-id/waltid-identity/tree/main/waltid-applications/waltid-crypto-ios-testApp"
    click iOSOpenID "https://github.com/walt-id/waltid-identity/tree/main/waltid-applications/waltid-openid4vc-ios-testApp"
    click DockerCompose "https://github.com/walt-id/waltid-identity/blob/main/docker-compose/docker-compose.yaml"
    click Vault "https://github.com/walt-id/waltid-identity/tree/main/docker-compose/vault"
    click Caddy "https://github.com/walt-id/waltid-identity/tree/main/docker-compose/Caddyfile"

    %% Styles
    classDef sdk fill:#D0E8FF,stroke:#036,stroke-width:1px
    classDef services fill:#DFF2D8,stroke:#090,stroke-width:1px
    classDef apps fill:#FFE4B3,stroke:#F90,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#999,stroke-width:1px
```
