# openwallet-foundation/multipaz architecture

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

- Interactive diagram: https://gitdiagram.com/openwallet-foundation/multipaz
- Repository: https://github.com/openwallet-foundation/multipaz

## Overview

##### Project Type and Purpose
- This is a single Git repository hosting a multi-module Kotlin Multiplatform (“KMP”) library suite plus supporting command-line tools, server-side microservices, and sample wallet apps.
- Core functionality: ISO mdoc, SD-JWT VCs, presentment (BLE, NFC, web), zero-knowledge proofs, cryptography, storage, RPC transport, plus UI components for Compose and Vision (barcode/face).

##### High-Level File Structure & Patterns
- Top‐level: Gradle settings, scripts, CI workflows.
- Library modules (all Gradle subprojects):
- multipaz (core commonMain domain logic + platformMain adapters)
- multipaz-models (stateful domain models)
- multipaz-compose (Compose UI components)
- multipaz-vision (camera/barcode/face utilities)
- multipaz-doctypes, multipaz-longfellow, multipaz-cbor-rpc (graph hashing + codegen)
- multipaz-android-legacy (old Java Android API)
- SwiftBridge & xcframework for iOS packaging
- CLI: multipazctl (thin wrapper over core libs)
- Server microservices (each a Ktor HTTP service):
- multipaz-backend-server (OpenID4VCI backend)
- multipaz-csa-server & multipaz-csa (cloud secure area)
- multipaz-openid4vci-server (issuer API)
- multipaz-records-server (record storage API)
- multipaz-verifier-server (VC verifier API)
- Sample cross‐platform app: samples/testapp (Android + iOS Compose Multiplatform)

##### Key Architectural Components
- Common Library Layer (KMP commonMain)
- Domain: mdoc, credential, cbor, cose, crypto, storage, rpc, provisioning, mdoc transport, ZK proofs, document types.
- Platform Adapter Layer (androidMain, iosMain, jvmMain, javaSharedMain)
- Concrete implementations: BLE/NFC transports, Android Keystore, iOS Secure Enclave, JDBC storage, HTTP transport via Ktor.
- Application & Tooling Layer
- CLI (multipazctl)
- Sample app (samples/testapp)
- SwiftBridge / xcframework for Swift usage
- Service Layer (microservices)
- Each service is an independent Ktor server module exposing REST/HTTP endpoints and static web assets; they depend on core provisioning / openid4vci / records / verification logic.

##### Relationships & Data Flows
- All apps, CLI, and servers depend on one or more core library modules.
- multipaz-models, compose, vision depend on multipaz core.
- microservices depend on multipaz core + provisioning/openid4vci sub-modules.
- SwiftBridge / xcframework wrap multipaz core for Swift clients.
- Sample apps & third-party apps use multipaz core to:
– Discover and engage BLE/NFC mdoc readers via transport adapters.
– Call provisioning/issuance APIs over HTTP to issuer microservices (openid4vci-server, backend-server).
– Present digital credentials via W3C DC API or URI schemes.
- CLI (multipazctl) executes local credential operations and can call remote services via HTTP.
- Verifier-server exposes VC verification endpoints; records-server stores and retrieves identity records; csa-server enforces cloud secure area policies.

##### Architectural Patterns & Principles
- Kotlin Multiplatform: share common business logic, isolate platform specifics.
- Hexagonal / Clean Separation: domain logic in commonMain, ports/adapters in platformMain, applications and services at the outer ring.
- Microservices: each backend function (issuance, storage, verification, CSA) is its own module with its own REST API and configuration.
- Code generation: multipaz-cbor-rpc uses Kotlin Symbol Processing for RPC stubs.
- Single monorepo with fine-grained modules, consistent Gradle KTS builds.

##### Essential Elements
- Module names exactly as in Gradle (`multipaz`, `multipaz-models`, etc.).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Libraries Swimlane
    subgraph "Libraries"
        direction TB
        lib_core["multipaz"]:::library
        lib_models["multipaz-models"]:::library
        lib_compose["multipaz-compose"]:::library
        lib_vision["multipaz-vision"]:::library
        lib_doctypes["multipaz-doctypes"]:::library
        lib_longfellow["multipaz-longfellow"]:::library
        lib_cbor_rpc["multipaz-cbor-rpc"]:::library
    end

    %% Platforms Swimlane
    subgraph "Platforms"
        direction TB
        plat_android["multipaz-android-legacy"]:::platform
        plat_swift["SwiftBridge / xcframework"]:::platform
    end

    %% Applications Swimlane
    subgraph "Applications"
        direction TB
        app_cli["multipazctl"]:::application
        app_sample["samples/testapp"]:::application
    end

    %% Backend Swimlane
    subgraph "Backend Services"
        direction TB
        svc_issuer["multipaz-backend-server\n(OpenID4VCI Backend)"]:::service
        svc_csa_lib["multipaz-csa"]:::service
        svc_csa["multipaz-csa-server\n(Cloud Secure Area API)"]:::service
        svc_openid["multipaz-openid4vci-server\n(OpenID4VCI Issuer API)"]:::service
        svc_records["multipaz-records-server\n(Record Storage API)"]:::service
        svc_verifier["multipaz-verifier-server\n(VC Verifier API)"]:::service
    end

    %% External Protocols
    ble["BLE"]:::external
    nfc["NFC"]:::external
    http["HTTP"]:::external

    %% Compile-time Dependencies
    lib_models -->|depends on| lib_core
    lib_compose -->|depends on| lib_core
    lib_vision -->|depends on| lib_core
    lib_doctypes -->|depends on| lib_core
    lib_longfellow -->|depends on| lib_core
    lib_cbor_rpc -->|depends on| lib_core

    plat_android -->|depends on| lib_core
    plat_swift -->|depends on| lib_core

    app_cli -->|depends on| lib_core
    app_cli -->|depends on| lib_models

    app_sample -->|depends on| lib_core
    app_sample -->|depends on| lib_compose
    app_sample -->|depends on| lib_vision

    svc_issuer -->|depends on| lib_core
    svc_issuer -->|depends on| lib_doctypes
    svc_csa_lib -->|depends on| lib_core
    svc_csa -->|depends on| svc_csa_lib
    svc_openid -->|depends on| lib_core
    svc_records -->|depends on| lib_core
    svc_verifier -->|depends on| lib_core

    %% Run-time Interactions
    app_sample -->|uses| ble --> plat_android
    app_sample -->|uses| http --> svc_openid
    app_sample -->|uses| http --> svc_issuer

    app_cli -->|uses| http --> svc_verifier
    app_cli -->|uses| http --> svc_records
    app_cli -->|uses| http --> svc_csa

    %% Click Events
    click lib_core "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz/src"
    click lib_models "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-models/src"
    click lib_compose "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-compose/src"
    click lib_vision "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-vision/src"
    click lib_doctypes "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-doctypes/src"
    click lib_longfellow "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-longfellow/src"
    click lib_cbor_rpc "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-cbor-rpc/src"
    click plat_android "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-android-legacy/src"
    click plat_swift "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz/SwiftBridge"
    click plat_swift "https://github.com/openwallet-foundation/multipaz/tree/main/xcframework/"
    click app_cli "https://github.com/openwallet-foundation/multipaz/tree/main/multipazctl/src"
    click app_sample "https://github.com/openwallet-foundation/multipaz/tree/main/samples/testapp/src"
    click svc_issuer "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-backend-server/src"
    click svc_csa_lib "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-csa/src"
    click svc_csa "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-csa-server/src"
    click svc_openid "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-openid4vci-server/src"
    click svc_records "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-records-server/src"
    click svc_verifier "https://github.com/openwallet-foundation/multipaz/tree/main/multipaz-verifier-server/src"

    %% Styles
    classDef library fill:#cce5ff,stroke:#5b9bd5
    classDef platform fill:#e6f2ff,stroke:#5b9bd5
    classDef application fill:#d4edda,stroke:#28a745
    classDef service fill:#ffe5cc,stroke:#ff9900
    classDef external fill:#f0f0f0,stroke:#666
```
