# iotaledger/identity architecture

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

- Interactive diagram: https://gitdiagram.com/iotaledger/identity
- Repository: https://github.com/iotaledger/identity

## Overview

##### Project Type and Purpose
- This is an open-source, multi-crate Rust library (monorepo) implementing Self-Sovereign Identity (SSI) with W3C DID & Verifiable Credentials.
- Provides language agnostic core crates, plus IOTA-specific DID method implementations, and FFI bindings for WebAssembly (JavaScript/TypeScript) and gRPC services.

##### Logical Layers & Top-Level Structure
- Root Workspace (Cargo.toml)
- Core Layer:
- identity_core
- identity_document
- identity_credential
- identity_did
- Crypto & Verification Layer:
- identity_jose (JWS/JWT)
- identity_verification (verification methods)
- identity_ecdsa_verifier, identity_eddsa_verifier, identity_pqc_verifier
- Storage & Key Management Layer:
- identity_storage (abstract storage)
- identity_stronghold (secure vault implementation)
- IOTA Integration Layer:
- identity_iota (IOTA DID method)
- identity_iota_core (Rebased network adapter + Move VM interactions)
- identity_resolver (DID resolution commands)
- Bindings Layer:
- bindings/wasm/identity_wasm (WASM build, TS API)
- bindings/grpc (proto definitions, gRPC server)
- Examples and Tests

##### Component Interactions & Data Flow
- External Client (Rust app, Node.js/TS, or gRPC consumer)
→ invokes high-level APIs exposed by the WASM module or gRPC service
→ FFI Binding Layer routes calls into native Rust crates
→ Core Layer handles generic DID/VC operations (create, sign, verify)
→ Crypto Layer uses JOSE and verifier crates to encode/decode JWS/JWT, SD-JWT, ZKP
→ Storage Layer persists keys and state (in-memory, Stronghold, custom backends)
→ IOTA Layer publishes DID documents to the Tangle, resolves documents via IOTA node
→ Resolver Layer orchestrates fetching and parsing DID documents from various methods
→ Results bubble back to the client

##### Architectural Patterns & Principles
- Modular crate-based design (separation of concerns, single responsibility)
- Layered architecture (Core, Crypto, Storage, Network, Bindings)
- Plugin-style DID method support (method-agnostic core + iota-specific implementation)
- FFI abstraction (Binding crates isolate environment-specific code)
- Dependency inversion for storage and network adapters (swapable backends)

##### Elements
- Components:
- Client Layer (Rust App, JS/TS Browser, gRPC Consumer)
- Binding Layer (WASM, gRPC Server)
- Core Crates Layer (document, credential, DID, core types)
- Crypto Layer (JOSE, verifier crates)
- Storage Layer (identity_storage interface, Stronghold vault)
- IOTA Layer (network adapter, Move VM module)
- Resolver Layer (DID resolution)
- Rectangles for Rust crates
- Clouds for external networks (IOTA node)
- Rounded rectangles for FFI bindings
- Clear Labels: component names, interfaces (e.g., “StorageAdapter”, “__wbindgen_exports__”), protocols (gRPC, HTTP/web).

##### Putting It All Together
- Within Core, show two sub-flows:
- Crypto Flow → identity_jose + verifier crates → Storage Layer → IOTA Layer → network
- Resolution Flow → identity_resolver → IOTA node fetch → parsing back into core types
- “Supports plugin for custom storage backends” and “Supports multiple signature algorithms via JOSE.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        RustExamples["Rust Examples"]:::client
        WASMClient["JS/TS Examples"]:::client
        GRPCClient["gRPC Consumer Tests"]:::client
    end

    %% Binding Layer
    subgraph "Binding Layer"
        direction TB
        WASMBinding["WASM Binding Module"]:::binding
        GRPCServer["gRPC Server"]:::binding
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        CoreTypes["identity_core"]:::core
        Document["identity_document"]:::core
        Credential["identity_credential"]:::core
        DID["identity_did"]:::core
    end

    %% Crypto & Verification Layer
    subgraph "Crypto & Verification Layer"
        direction TB
        JOSE["identity_jose"]:::crypto
        Verif["identity_verification"]:::crypto
        ECDSA["identity_ecdsa_verifier"]:::crypto
        EdDSA["identity_eddsa_verifier"]:::crypto
        PQC["identity_pqc_verifier"]:::crypto
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        StorageIfc["identity_storage"]:::storage
        Stronghold["identity_stronghold"]:::storage
    end

    %% IOTA Integration Layer
    subgraph "IOTA Integration Layer"
        direction TB
        IOTAmeth["identity_iota"]:::network
        IOTACore["identity_iota_core"]:::network
    end

    %% Resolver Layer
    subgraph "Resolver Layer"
        direction TB
        Resolver["identity_resolver"]:::network
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        IOTANode["IOTA Node"]:::external
        KeyVault["Key Vault"]:::external
    end

    %% Data Flows
    RustExamples -->|uses| WASMBinding
    WASMClient -->|uses| WASMBinding
    GRPCClient -->|calls| GRPCServer

    WASMBinding -->|FFI calls| CoreTypes
    GRPCServer -->|RPC calls| CoreTypes

    CoreTypes -->|uses| Document
    CoreTypes -->|uses| Credential
    CoreTypes -->|uses| DID

    CoreTypes -->|crypto ops| JOSE
    CoreTypes -->|crypto ops| Verif
    JOSE -->|signature| ECDSA
    JOSE -->|signature| EdDSA
    JOSE -->|signature| PQC

    JOSE -->|key fetch| StorageIfc
    Verif -->|verification| StorageIfc

    StorageIfc -->|vault| Stronghold
    Stronghold -->|secure store| KeyVault

    CoreTypes -->|resolve| Resolver
    Resolver -->|network fetch| IOTANode

    StorageIfc -->|publish DID| IOTAmeth
    IOTAmeth -->|adapter calls| IOTACore
    IOTACore -->|network| IOTANode

    %% Click Events
    click RustExamples "https://github.com/iotaledger/identity/tree/main/examples/"
    click WASMClient "https://github.com/iotaledger/identity/tree/main/bindings/wasm/identity_wasm/examples"
    click GRPCClient "https://github.com/iotaledger/identity/tree/main/bindings/grpc/tests/api"
    click GRPCServer "https://github.com/iotaledger/identity/tree/main/bindings/grpc/src/"
    click WASMBinding "https://github.com/iotaledger/identity/blob/main/bindings/wasm/identity_wasm/src/lib.rs"
    click CoreTypes "https://github.com/iotaledger/identity/tree/main/identity_core/src/"
    click Document "https://github.com/iotaledger/identity/tree/main/identity_document/src/"
    click Credential "https://github.com/iotaledger/identity/tree/main/identity_credential/src/"
    click DID "https://github.com/iotaledger/identity/tree/main/identity_did/src/"
    click JOSE "https://github.com/iotaledger/identity/tree/main/identity_jose/src/"
    click Verif "https://github.com/iotaledger/identity/tree/main/identity_verification/src/"
    click ECDSA "https://github.com/iotaledger/identity/tree/main/identity_ecdsa_verifier/src/"
    click EdDSA "https://github.com/iotaledger/identity/tree/main/identity_eddsa_verifier/src/"
    click PQC "https://github.com/iotaledger/identity/tree/main/identity_pqc_verifier/src/"
    click StorageIfc "https://github.com/iotaledger/identity/tree/main/identity_storage/src/"
    click Stronghold "https://github.com/iotaledger/identity/tree/main/identity_stronghold/src/"
    click IOTAmeth "https://github.com/iotaledger/identity/tree/main/identity_iota/src/"
    click IOTACore "https://github.com/iotaledger/identity/tree/main/identity_iota_core/src/"
    click Resolver "https://github.com/iotaledger/identity/tree/main/identity_resolver/src/"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef binding fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px
    classDef crypto fill:#ffb,stroke:#333,stroke-width:1px
    classDef storage fill:#fbf,stroke:#333,stroke-width:1px
    classDef network fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
```
