# jolocom/jolocom-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/jolocom/jolocom-sdk
- Repository: https://github.com/jolocom/jolocom-sdk

## Overview

##### Main Components
- Agent Factory (src/agent.ts): Central to creating and managing agents. Acts as an entry point for consumers of the SDK.
- Interaction Manager (src/interactionManager/): Houses various “flows” (authentication, authorization, credential issuance, signing, encryption/decryption, etc.) that control interactions between agents. Each flow has its own module (e.g., authenticationFlow, signingFlow) that should be depicted as sub-components.
- Channels (src/channels/): Manages communication channels between agents. This area includes generic channel definitions, channel keeper functionalities and is crucial for the transmission of messages and data.
- DID & Credential Handling (src/credentials.ts, src/didMethodKeeper.ts, src/resolution.ts): These components manage decentralized identifiers (DIDs) and verifiable credentials. They interface with both external DID methods (see the compatibility module in src/compat/) and internal resolution and storage.
- Storage (src/storage/): Responsible for persisting agent states and related data (e.g., keys, credentials). This is a backend module that the Agent and Interaction Manager leverage.
- Transports & Communication (src/http.ts, src/websocket.ts, src/transports.ts): These modules provide different transport mechanisms to communicate with external networks or other agents.
- Error Handling & Utilities (src/errors.ts, src/util.ts): Support components for exception logging and common utility functions across the SDK.

##### Relationships and Interactions
- The Agent Factory is tightly coupled with Storage and DID Method Keeper components, as it sets up each new agent with proper access to stored identities and DID resolution.
- The Interaction Manager serves as the orchestrator for many handshakes and interaction flows (like credential offers or authorization). It communicates with Channels to send/receive messages, with the Storage module for stateful information, and with DID/credential components to validate identities.
- The Channels component acts as an intermediary for all communications, sending messages through different transport methods (HTTP, WebSocket).
- The compatibility modules ensure that the SDK can work with external crypto libraries or DID method libraries (e.g., jolocomLib and cryptojs).
- Error handling and utility functions support all these processes, ensuring that flows are robust and maintain consistent behaviors.

##### Architectural Patterns
- Modular Design & Separation of Concerns: Each major functional area is cleanly divided into specific directories (e.g., interactions, channels, storage) to ensure maintainability.
- Flow-based Interaction: The interaction manager’s distinct flows (authentication, signing, etc.) suggest a pattern where each flow encapsulates distinct logic, making the system easily extensible.
- Extensibility and Plugability: With dedicated directories for DID methods and external crypto, the SDK supports plugin-like extensions to adapt to various decentralized identity specifications.

##### Relevant Technologies/Frameworks
- The SDK is built with TypeScript (as indicated by .ts files) and uses Babel for transpilation (babel.config.js) and Jest for testing.
- Integration with specification standards (W3C DIDs and Verifiable Credentials) is a central design choice.
- The repository also contains CI/CD configurations (GitHub workflows) and documentation tools (mkdocs, docs folder) which, while not core to runtime architecture, are important for deployment and continuous integration.

##### Specific Elements
- Sub-components depicted under the Interaction Manager to illustrate the different “flow” modules.
- Notation of third-party integrations (crypto libraries, DID Methods) by grouping the Compatibility layer.
- Annotation for standards (W3C DIDs and VCs) that are inherent to the processing logic across components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core SDK
    subgraph "Core SDK"
        AF("Agent Factory"):::core
        IM("Interaction Manager"):::core
    end

    %% Interaction Flows
    subgraph "Interaction Flows"
        AFLO("Authentication Flow"):::core
        SF("Signing Flow"):::core
    end

    %% Supporting Services
    subgraph "Supporting Services"
        CH("Channels"):::service
        ST("Storage"):::service
        subgraph "DID & Credential Handling"
            DOPS("DID & Credential Operations"):::service
            DMK("DID Method Keeper"):::service
            RES("Resolution"):::service
            COMP("Compatibility"):::service
        end
        subgraph "Transports & Communication"
            HTTP("HTTP Communication"):::transport
            WS("WebSocket Communication"):::transport
            CT("Combined Transports"):::transport
        end
    end

    %% Error Handling & Utilities
    subgraph "Error Handling & Utilities"
        ERR("Error Handling"):::utility
        UTIL("Utilities"):::utility
    end

    %% Relationships between Core SDK and Supporting Services
    AF -->|"initializes"| ST
    AF -->|"configures"| DOPS
    IM -->|"orchestrates"| AFLO
    IM -->|"orchestrates"| SF
    IM -->|"communicates"| CH
    IM -->|"persists"| ST
    IM -->|"validates"| DOPS
    DOPS -->|"manages"| DMK
    DOPS -->|"manages"| RES

    %% Channels and Transports
    CH -->|"routes"| CT
    CT -->|"via"| HTTP
    CT -->|"via"| WS

    %% Logging/Error Reporting (dashed connections)
    AF ---|"logs"| ERR
    IM ---|"logs"| ERR
    CH ---|"logs"| ERR
    ST ---|"logs"| ERR
    DOPS ---|"logs"| ERR
    CT ---|"logs"| ERR

    %% Click Events
    click AF "https://github.com/jolocom/jolocom-sdk/blob/main/src/agent.ts"
    click IM "https://github.com/jolocom/jolocom-sdk/tree/main/src/interactionManager/"
    click AFLO "https://github.com/jolocom/jolocom-sdk/blob/main/src/interactionManager/authenticationFlow.ts"
    click SF "https://github.com/jolocom/jolocom-sdk/blob/main/src/interactionManager/signingFlow.ts"
    click CH "https://github.com/jolocom/jolocom-sdk/tree/main/src/channels/"
    click ST "https://github.com/jolocom/jolocom-sdk/tree/main/src/storage/"
    click DOPS "https://github.com/jolocom/jolocom-sdk/blob/main/src/credentials.ts"
    click DMK "https://github.com/jolocom/jolocom-sdk/blob/main/src/didMethodKeeper.ts"
    click RES "https://github.com/jolocom/jolocom-sdk/blob/main/src/resolution.ts"
    click COMP "https://github.com/jolocom/jolocom-sdk/tree/main/src/compat/"
    click HTTP "https://github.com/jolocom/jolocom-sdk/blob/main/src/http.ts"
    click WS "https://github.com/jolocom/jolocom-sdk/blob/main/src/websocket.ts"
    click CT "https://github.com/jolocom/jolocom-sdk/blob/main/src/transports.ts"
    click ERR "https://github.com/jolocom/jolocom-sdk/blob/main/src/errors.ts"
    click UTIL "https://github.com/jolocom/jolocom-sdk/blob/main/src/util.ts"

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px,color:#000
    classDef service fill:#90EE90,stroke:#333,color:#000
    classDef transport fill:#ADD8E6,stroke:#333,color:#000
    classDef utility fill:#FFB6C1,stroke:#333,color:#000
```
