# openwallet-foundation/acapy architecture

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

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

## Overview

a. The Agent Core: Represent the central “brain” that integrates all functionality such as protocol routing, event dispatching, configuration management, and the plugin system.
c. Wallet and Key Management: Show the wallet component which handles secure storage, key operations, and supports multiple key types as well as the integration with Askar and anoncreds.
f. Admin API / Controller Interface: Indicate that ACA-Py exposes an OpenAPI-documented REST administrative API (including webhook callbacks) that external controllers use to drive business logic.

##### Relationships and interactions
b. That the Agent Core routes messages to specific protocol handlers (e.g., didexchange or issue credential protocols) and dispatches events to the webhook interface.
d. That the Transport modules connect the ACA-Py internal processing engine with network endpoints (e.g., HTTP inbound transport receiving messages and outbound transport sending messages).
e. Dependency flows for configuration, logging, and the injection system to show cross-cutting concerns.

##### Use appropriate architectural patterns/design principles
a. Layering: Visually separate the external API layer, core business logic (protocol handlers, core modules), and lower-level infrastructure (transport, resolution, storage).
c. Extensibility: The dynamic plugin loading mechanism should be shown as an adjunct to the core engine – signifying that new functionality is added without tightly coupling to the core code.
d. Multi-tenancy and Scalability: Illustrate that the ACA-Py deployment can be scaled (either as a single container image or within microservice-like containers) and supports multi-tenant architectures with dedicated secure storage components.
e. API Security: Although not a strict component, note that the Admin API has secure (or insecure, in dev) modes using API keys.

c. Annotations (such as notes on security aspects or plugin extensibility) to give context to the component.
d. Validate that all critical ACA-Py capabilities (protocols, wallet, ledger, DID handling, inbound/outbound communications) and deployment elements (Docker, Helm, Kubernetes) are represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    subgraph "External Interfaces"
        ext["External Controller"]:::external
        api["Admin API"]:::external
    end

    %% Core Business Logic Layer
    subgraph "Core Business Logic"
        agent["Agent Core"]:::core
        protocols["Protocol Handlers"]:::core
        plugin["Plugin System"]:::core
    end

    %% Business Services Layer
    subgraph "Business Services"
        wallet["Wallet & Key Management"]:::modules
        ledger["Ledger"]:::modules
        did["DID Management"]:::modules
    end

    %% Transport Subsystems Layer
    subgraph "Transport Subsystems"
        inbound["Inbound Transport"]:::infra
        outbound["Outbound Transport"]:::infra
    end

    %% Deployment & Infrastructure Layer
    subgraph "Deployment & Infrastructure"
        container["Containerization"]:::deployment
        scripts["Deployment Scripts"]:::deployment
    end

    %% Relationships - External to Core
    ext -->|"REST_calls"| api
    api -->|"invokes"| agent

    %% Core internal interactions
    agent -->|"routes_to"| protocols
    agent -->|"integrates"| plugin

    %% Core to Business Services
    agent -->|"uses"| wallet
    wallet -->|"interacts_with"| ledger
    wallet -->|"interacts_with"| did

    %% Transport interactions
    inbound -->|"feeds"| agent
    agent -->|"dispatches_via"| outbound

    %% Deployment connections
    agent -->|"deployed_on"| container
    container -->|"orchestrated_by"| scripts

    %% Click Events
    click agent "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/core"
    click api "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/admin"
    click protocols "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/protocols"
    click wallet "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/wallet"
    click ledger "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/ledger"
    click did "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/did"
    click inbound "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/transport/inbound"
    click outbound "https://github.com/openwallet-foundation/acapy/tree/main/acapy_agent/transport/outbound"
    click plugin "https://github.com/openwallet-foundation/acapy/blob/main/acapy_agent/core/plugin_registry.py"
    click container "https://github.com/openwallet-foundation/acapy/tree/main/charts/acapy"
    click scripts "https://github.com/openwallet-foundation/acapy/tree/main/demo/"

    %% Styles
    classDef external fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef core fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef modules fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef infra fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
    classDef deployment fill:#DDA0DD,stroke:#9932CC,stroke-width:2px;
```
