# cardano-foundation/veridian-wallet architecture

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

- Interactive diagram: https://gitdiagram.com/cardano-foundation/veridian-wallet
- Repository: https://github.com/cardano-foundation/veridian-wallet

## Overview

##### Main Components
- Mobile Client: Represent the native mobile apps (Android and iOS) that harness Capacitor to bridge web technologies with native functionalities (e.g., biometric authentication via secure enclaves/TEEs).
- Web Frontend: The core user interface implemented in React and organized under the “src/ui” and “src/pages” directories, complete with UI components, routing, and state management.
- Core SSI & Agent Library: The “src/core/agent” (along with related storage and configuration modules) encapsulates the wallet’s fundamental SSI operations – including KERI event handling and secure storage.
- Backend Services: Several microservices (e.g., “services/credential-server”, “services/credential-server-ui”, and the sample dApp under “services/cip45-sample-dapp”) provide the business logic to manage credentials, handle APIs for network communication, and facilitate interactions with external systems.
- External and Cloud Agents: Highlight integrations with external SSI services such as the KERIA cloud agent, Signify-TS, and any Cardano-based external services (e.g., Cardano Backer and CIP-45 for dApp integration).

##### Relationships and Interactions
- The frontends (mobile and web) interact with the core SSI agent and underlying storage layers via well-structured APIs.
- The mobile and web clients communicate with backend services through HTTP/REST and/or WebSocket interfaces (as configured by Docker and orchestrated in “docker-compose.yaml” files).
- There is a clear data flow from user interactions in the UI to the agent’s secure storage (managed through modules like “ionicStorage”, “secureStorage”, “sqliteStorage”) and then to the server services handling credential issuance or verification.
- External integrations (e.g., to Cardano and KERIA cloud agents) are connected to the backend services and, in turn, influence the agent’s operation.

##### Architectural Patterns and Key Principles
- Separation of Concerns: There’s a clear demarcation between the UI (presentation layer), the domain logic (agent, SSI operations), and the backend/microservices (credential server, API gateways).
- Modular Microservices Architecture: Under the “services” directory, there are independently deployable components, making use of Docker (with dedicated Dockerfiles and docker-compose configuration) for encapsulation and deployment.
- Cross-Platform Development: The use of Capacitor bridges the web application with native mobile capabilities, and distinct folders for Android and iOS ensure native integration.
- Security by Design: The system leverages secure storage modules and integration with Secure Enclaves and Trusted Execution Environments, which is crucial for handling credentials and private keys.

##### Relevant Technologies, Frameworks, and Libraries
- Node.js and npm for server-side operations; Webpack for building assets (webpack.dev.cjs, etc.).
- TypeScript throughout (e.g., tsconfig.json files in various directories).
- React as the UI framework (evidenced by “src/ui”, “src/pages”, and component organization).
- Capacitor for mobile integration.
- Docker / Docker Compose for containerizing backend services.
- Integration with SSI protocols – KERI, CESR, and frameworks such as Signify-TS.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Applications"
        subgraph "Mobile Clients"
            A("Android (Capacitor)"):::client
            B("iOS (Capacitor)"):::client
        end
        subgraph "Web Frontend"
            C("React UI (Web Frontend)"):::client
        end
    end

    subgraph "Core SSI & Agent Library"
        D("Core Agent Library (KERI & SSI)"):::core
        E("Secure Storage Modules"):::storage
    end

    subgraph "Backend Services"
        F("Credential Server (Backend)"):::service
        G("Credential Server UI"):::service
        H("Sample dApp (CIP-45)"):::service
    end

    I("KERIA Cloud Agent & Cardano Services"):::external

    %% Connections from Clients to Core Agent
    A -->|"interacts"| D
    B -->|"interacts"| D
    C -->|"interacts"| D

    %% Core Agent uses Secure Storage
    D -->|"uses"| E

    %% Core Agent communicates with Backend Services
    D -->|"API_calls"| F
    D -->|"API_calls"| G
    D -->|"API_calls"| H

    %% Backend Services integrate with External Systems
    F -->|"integrates"| I
    G -->|"integrates"| I
    H -->|"integrates"| I

    %% Click Events
    click A "https://github.com/cardano-foundation/veridian-wallet/tree/main/android"
    click B "https://github.com/cardano-foundation/veridian-wallet/tree/main/ios"
    click C "https://github.com/cardano-foundation/veridian-wallet/tree/main/src/ui"
    click C "https://github.com/cardano-foundation/veridian-wallet/tree/main/src/pages"
    click D "https://github.com/cardano-foundation/veridian-wallet/tree/main/src/core/agent"
    click E "https://github.com/cardano-foundation/veridian-wallet/tree/main/src/core/storage"
    click F "https://github.com/cardano-foundation/veridian-wallet/tree/main/services/credential-server"
    click G "https://github.com/cardano-foundation/veridian-wallet/tree/main/services/credential-server-ui"
    click H "https://github.com/cardano-foundation/veridian-wallet/tree/main/services/cip45-sample-dapp"
    click I "https://github.com/cardano-foundation/veridian-wallet/tree/main/keria-config"

    %% Styles
    classDef client fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef core fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef storage fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef service fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef external fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
```
