# hyperledger-identus/cloud-agent architecture

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

- Interactive diagram: https://gitdiagram.com/hyperledger-identus/cloud-agent
- Repository: https://github.com/hyperledger-identus/cloud-agent

## Overview

##### Main Components
- Cloud Agent Core: This serves as the central service providing the REST API endpoints for identity management, DID handling, and credential issuance/verification.
- Communication & DID Protocols: Represent the DIDComm V2 and protocol-specific submodules (for issuing, verifying, presenting credentials, and handling different DID methods such as “did:prism” and “did:peer”). These are implemented across modules (for example in “castor”, “connect”, “pollux”, “prism-node”, “mercury”, etc.).
- External Dependencies:
– Secrets Management: Illustrate the Hashicorp Vault integration (as indicated in configuration options) for secure storage and key management.
– PRISM Node: A distinct component that may be used in certain configurations, with a note about compatibility (the README provides a version compatibility table).
– Event Notification Service: A module responsible for HTTP events and webhook notifications.
- Controller / Business Logic Layer: Although the Cloud Agent itself is a backend service, it is designed to be controlled by an external business logic controller (built in any language) that interacts with the agent via HTTP. Thus include the “controller” as an external consumer.
- Infrastructure & Deployment: Containers, Docker images, and container orchestration as defined by “infrastructure”, “docker-compose” files, Helm charts, etc.

##### Architectural Patterns and Relationships
- Data Flow: Indicate where events are triggered (e.g., webhook notifications) and flows from inbound HTTP requests to back-end protocol processing modules.
- Middleware Components: If needed, include modules for logging (as suggested by configuration files), authentication (OIDC, API keys, etc.), and message brokers for asynchronous messaging (noting messaging support in “shared/messaging” and event notification modules).

##### Reference to Underlying Technologies
- Scala / SBT: Represent that the main service is implemented in Scala (noting presence of “build.sbt” and many Scala source folders).
- Containerization: Show Docker, Docker Compose, and orchestration elements as part of the infrastructure layer.
- External Services: Clearly mark integration points for Cardano, Vault, and PRISM Node.

- Optionally, include additional details like version compatibility notes (e.g., between Cloud Agent and PRISM Node) as annotations.
- Error flows or status endpoints (as indicated by health checks in the README).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces"
        E["External Controller – API Client Libraries"]:::external
    end

    %% Core Services
    subgraph "Cloud Agent Core Services"
        CA["Cloud Agent – REST API & DIDComm Processing"]:::internal
        AUTH["Authentication & Authorization Middleware"]:::middleware
    end

    %% DID Communication & Protocols
    subgraph "DID Communication & Protocols"
        CASTOR["Castor – DID Models & Protocols"]:::internal
        CONNECT["Connect – DIDComm Connections"]:::internal
        POLLUX["Pollux – Credential Issuance/Presentation"]:::internal
        MERCURY["Mercury – Additional DIDComm Processing"]:::internal
    end

    %% Integrations with External Systems
    subgraph "Integrations"
        PRISM["PRISM Node Integration (Distributed Ledger)"]:::internal
        VAULT["Vault – Secrets Management"]:::internal
        EVENT["Event Notification Service (Webhooks)"]:::internal
    end

    %% Shared Middleware & Utilities
    subgraph "Shared & Utilities"
        SHARED["Shared Messaging & Utilities"]:::internal
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        INFRA["Containers / Docker-Compose / Helm Charts"]:::infra
    end

    %% Relationships / Data Flow
    E -->|"HTTPcalls"| CA
    CA -->|"auth"| AUTH
    CA -->|"initiate protocols"| CASTOR
    CA -->|"initiate protocols"| CONNECT
    CA -->|"credential flows"| POLLUX
    CA -->|"DIDComm actions"| MERCURY
    CA -->|"ledger ops"| PRISM
    CA -->|"key management"| VAULT
    CA -->|"event triggers"| EVENT
    CA -->|"messaging"| SHARED
    CA -->|"deployed via"| INFRA

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef middleware fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef infra fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;

    %% Click Events
    click CA "https://github.com/hyperledger-identus/cloud-agent/blob/main/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/CloudAgentApp.scala"
    click CASTOR "https://github.com/hyperledger-identus/cloud-agent/tree/main/castor/src/main/scala/org/hyperledger/identus/castor"
    click CONNECT "https://github.com/hyperledger-identus/cloud-agent/tree/main/connect/core/src/main/scala/org/hyperledger/identus/connect"
    click POLLUX "https://github.com/hyperledger-identus/cloud-agent/tree/main/pollux/core/src/main/scala/org/hyperledger/identus/pollux/core"
    click MERCURY "https://github.com/hyperledger-identus/cloud-agent/tree/main/mercury/agent-didcommx/src/main/scala/org/hyperledger/identus/mercury"
    click PRISM "https://github.com/hyperledger-identus/cloud-agent/tree/main/prism-node/client/scala-client"
    click VAULT "https://github.com/hyperledger-identus/cloud-agent/tree/main/cloud-agent/service/wallet-api/src/main/scala/org/hyperledger/identus/agent/walletapi/vault"
    click EVENT "https://github.com/hyperledger-identus/cloud-agent/tree/main/event-notification/src/main/scala/org/hyperledger/identus/event/notification"
    click E "https://github.com/hyperledger-identus/cloud-agent/tree/main/cloud-agent/client"
    click SHARED "https://github.com/hyperledger-identus/cloud-agent/tree/main/shared/core/src/main/scala/org/hyperledger/identus/shared/messaging"
    click AUTH "https://github.com/hyperledger-identus/cloud-agent/tree/main/cloud-agent/service/server/src/main/scala/org/hyperledger/identus/iam/authentication"
    click INFRA "https://github.com/hyperledger-identus/cloud-agent/tree/main/infrastructure"
```
