# hyperledger-identus/sdk-swift architecture

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

- Interactive diagram: https://gitdiagram.com/hyperledger-identus/sdk-swift
- Repository: https://github.com/hyperledger-identus/sdk-swift

## Overview

##### Project type and purpose
- This is a multi‐module Swift SDK (library) for building Self-Sovereign Identity (SSI) apps on Apple platforms using Atala PRISM.
- It exposes separate “building block” modules (Apollo, Castor, Pollux, Mercury, Pluto) plus an orchestration layer called EdgeAgent.
- It includes core helpers (Core), end-to-end test harness (E2E), documentation (EdgeAgentSDK docs folder), and sample SwiftUI apps (Sample/…).

##### Top-level file structure and architectural slices
- Core – low-level helpers (JSON, Base64, async/await shims, logging).
- Building blocks (each a separate Swift Package target under EdgeAgentSDK):
– Apollo: cryptographic primitives
– Castor: DID creation & resolution
– Pollux: credential issuance & verification
– Mercury: secure messaging (DIDComm)
– Pluto: portable storage abstraction (CoreData, Keychain)
- EdgeAgent – orchestrates building blocks to present high-level DID/credential API.
- Domain – shared models and helper extensions used by building blocks & EdgeAgent.
- E2E – custom BDD-style test framework + test suites exercising the SDK against a cloud agent.
- Sample – three SwiftUI demo applications showing real-world integration: Challenger app, Wallet demo, Chat app.
- Docs – DocC‐based documentation under EdgeAgentSDK/Sources/EdgeAgentSDK.docc.

##### Insights from README
- Lists the building blocks and their purposes.
- Emphasizes use of Swift Package Manager, Xcode, target Apple OS versions.

– Core (helpers & logging)
– Domain (shared models)
– Apollo, Castor, Pollux, Mercury, Pluto (building-block modules)
– EdgeAgent (agent orchestration layer)
– E2E Test Framework (BDD runner + test suites)
– Sample Apps (AtalaPRISM Challenger, WalletDemo, DIDChat)
– External Services: Cardano network / cloud-agent (for DID/credential issuance), Mediator service (DIDComm V2)
– Core → Domain → Building Blocks → EdgeAgent → Sample Apps / E2E
– EdgeAgent → each Building Block (invokes crypto, DID, credential, messaging, storage)
– Building Blocks → Domain (use shared models)
– Sample Apps → EdgeAgent API (calls connect, issueCredential, presentProof, etc.)
– E2E → EdgeAgent (scripts exercise agent flows against cloud-agent)
– EdgeAgent & Mercury → Mediator service (for DIDComm)
– EdgeAgent / Castor → Cardano blockchain via cloud-agent
c. Architectural patterns & principles:
– Modular “building-blocks” pattern
– Layered architecture: Core → Domain → Building Blocks → Orchestration → Consumers
– Port & adapter: Pluto abstracts storage, Mercury abstracts transport, enabling pluggability
– Dependency inversion: high-level EdgeAgent depends on low-level building-blocks via protocols
d. Key technologies & frameworks:
– Swift Package Manager targets
– Swift concurrency (async/await, Futures)
– CoreData, Keychain (via Pluto)
– DIDComm V2
– DocC for SDK docs
– Custom BDD test framework (E2E)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core & Domain Layer
    subgraph "Core & Domain"
        Core["Core\nhelpers & logging"]:::grey
        Domain["Domain\nshared models"]:::grey
        Docs["DocC Documentation"]:::grey
    end

    %% Building Blocks Layer
    subgraph "Building Blocks"
        Apollo["Apollo\ncrypto primitives"]:::blue
        Castor["Castor\nDID creation & resolution"]:::blue
        Pollux["Pollux\ncredential issuance & verification"]:::blue
        Mercury["Mercury\nsecure messaging\n(DIDComm)"]:::blue
        Pluto["Pluto\nstorage abstraction"]:::blue
    end

    %% Orchestration Layer
    subgraph "EdgeAgent Orchestration"
        EdgeAgent["EdgeAgent\norchestration layer"]:::green
    end

    %% Consumers
    subgraph "Consumers"
        Challenger["AtalaPRISM Challenger App"]:::orange
        WalletDemo["Wallet Demo App"]:::orange
        DIDChat["DIDChat App"]:::orange
        E2E["E2E Test Framework & Suites"]:::orange
    end

    %% External Services
    subgraph "External Services"
        Mediator["Mediator Service\n(DIDComm V2)"]:::pink
        Cardano["Cardano Blockchain\nvia Cloud-Agent"]:::pink
    end

    %% Relationships
    Core --> Domain
    Domain --> Apollo
    Domain --> Castor
    Domain --> Pollux
    Domain --> Mercury
    Domain --> Pluto

    EdgeAgent --> Apollo
    EdgeAgent --> Castor
    EdgeAgent --> Pollux
    EdgeAgent --> Mercury
    EdgeAgent --> Pluto

    Apollo --> EdgeAgent
    Castor --> EdgeAgent
    Pollux --> EdgeAgent
    Mercury --> EdgeAgent
    Pluto --> EdgeAgent

    Challenger --> EdgeAgent
    WalletDemo --> EdgeAgent
    DIDChat --> EdgeAgent
    E2E --> EdgeAgent

    EdgeAgent --> Mediator
    Mercury --> Mediator

    EdgeAgent --> Cardano
    Castor --> Cardano

    %% Documentation connections
    Docs --> Apollo
    Docs --> Castor
    Docs --> Pollux
    Docs --> Mercury
    Docs --> Pluto
    Docs --> EdgeAgent

    %% Click Events
    click Core "https://github.com/hyperledger-identus/sdk-swift/tree/main/Core/Sources"
    click Domain "https://github.com/hyperledger-identus/sdk-swift/tree/main/EdgeAgentSDK/Domain/Sources"
    click Apollo "https://github.com/hyperledger-identus/sdk-swift/tree/main/EdgeAgentSDK/Apollo/Sources"
    click Castor "https://github.com/hyperledger-identus/sdk-swift/tree/main/EdgeAgentSDK/Castor/Sources"
    click Pollux "https://github.com/hyperledger-identus/sdk-swift/tree/main/EdgeAgentSDK/Pollux/Sources"
    click Mercury "https://github.com/hyperledger-identus/sdk-swift/tree/main/EdgeAgentSDK/Mercury/Sources"
    click Pluto "https://github.com/hyperledger-identus/sdk-swift/tree/main/EdgeAgentSDK/Pluto/Sources"
    click EdgeAgent "https://github.com/hyperledger-identus/sdk-swift/tree/main/EdgeAgentSDK/EdgeAgent/Sources"
    click Docs "https://github.com/hyperledger-identus/sdk-swift/blob/main/EdgeAgentSDK/EdgeAgentSDK/Sources/EdgeAgentSDK.docc"
    click Challenger "https://github.com/hyperledger-identus/sdk-swift/tree/main/Sample/AtalaPrismChallengerAppDemo/atala-prism-challenger-app"
    click WalletDemo "https://github.com/hyperledger-identus/sdk-swift/tree/main/Sample/AtalaPrismWalletDemo/AtalaPrismWalletDemo"
    click DIDChat "https://github.com/hyperledger-identus/sdk-swift/tree/main/Sample/DIDChat/DIDChat"
    click E2E "https://github.com/hyperledger-identus/sdk-swift/tree/main/E2E/TestFramework"
    click E2E "https://github.com/hyperledger-identus/sdk-swift/tree/main/E2E/Tests"

    %% Styles
    classDef grey fill:#d3d3d3,stroke:#555,stroke-width:1px;
    classDef blue fill:#add8e6,stroke:#555,stroke-width:1px;
    classDef green fill:#90ee90,stroke:#555,stroke-width:1px;
    classDef orange fill:#ffcc99,stroke:#555,stroke-width:1px;
    classDef pink fill:#ffb6c1,stroke:#555,stroke-width:1px;
```
