# input-output-hk/mithril architecture

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

- Interactive diagram: https://gitdiagram.com/input-output-hk/mithril
- Repository: https://github.com/input-output-hk/mithril

## Overview

##### Project type and purpose
- This is a multi-service, full-stack, microservice-style system implementing the Mithril threshold multisignature protocol on top of the Cardano network.
- The main runtime nodes are: Mithril Signer (produces individual signatures), Mithril Aggregator (collects and aggregates signatures into certified artifacts), Mithril Relay (peer-to-peer message forwarder), and Clients (CLI, WASM, library). There is also an Explorer frontend, internal shared libraries, an end-to-end test lab, and Terraform-based cloud infrastructure.

##### High-level file structure signals
- Top-level Rust crates:
- mithril-aggregator
- mithril-signer
- mithril-relay
- mithril-client, mithril-client-cli, mithril-client-wasm
- mithril-common, mithril-stm
- Frontend: mithril-explorer (Next.js/React)
- Infra: mithril-infra (Terraform + Docker-Compose + scripts)
- Test suites & demos under demo/ and mithril-test-lab/

##### Key runtime components
A. Cardano Network
– Source of chain data, state snapshots, and stake distribution.
B. Mithril Signers
– Connect to Cardano node, compute partial signatures, expose HTTP or P2P endpoints to send signatures.
C. Mithril Relay
– Optional P2P overlay that forwards signature messages between signers and aggregator.
D. Mithril Aggregator
– HTTP server (src/http_server) exposing artifact and proof APIs.
– Services layer (src/services) builds, certifies, and snapshot artifacts.
– Persistence (internal/mithril-persistence, SQLite) for open messages, certificates, epoch settings.
– File uploader (GCP, local) to store artifacts in cloud or local storage.
E. Clients
– CLI (Rust) and WASM/JS clients fetch artifacts via HTTP, verify proofs using mithril-stm and mithril-common.
F. Explorer
– Next.js frontend consuming Aggregator HTTP API, displaying certificates and artifacts.
G. Infrastructure
– Terraform modules and Docker-Compose files to deploy Cardano nodes, signers, aggregators, relays, reverse proxy (Traefik), monitoring (Prometheus, Loki), and VMs.
H. Test Lab
– Private devnet (Docker scripts), end-to-end scenarios, stress tests to validate protocol.

##### Component interactions
- Cardano → Signers and Aggregator: fetch chain data & current stake.
- Signers → Relay (optional) → Aggregator: send individual signature messages.
- Aggregator → Persistence: store messages and certificates in SQLite.
- Aggregator → FileUploader → Cloud Storage: store certified snapshots (JSON, tarballs).
- Clients & Explorer → Aggregator HTTP API: retrieve snapshot lists, proofs, statistics.
- Clients (Rust/WASM) → mithril-stm & mithril-common: verify multi-signature proofs.
- Infrastructure (Terraform) → Deploy: all services and supporting Cardano nodes.
- Test Lab → Spins up full network stack → runs automated tests.

##### Architectural patterns & design principles
- Hexagonal architecture / Clean architecture in each Rust service:
- Commands → Services → Repositories → Database / FileStorage
- Dependency Injection (builder & containers modules)
- Event sourcing for Aggregator’s internal state machine (event_store module)
- CI/CD with GitHub Actions for building crates, Docker images, publishing NPM/Cargo packages
- Infrastructure as Code (Terraform, Nix) for reproducible environments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% System Context
    Cardano["Cardano Network"]:::external
    CloudStorage["Cloud Storage"]:::external
    Infra["Infrastructure\n(Terraform, Docker)"]:::infra
    TestLab["Test Lab"]:::infra

    subgraph "Runtime Nodes"
        Signer["Mithril Signer\n(Rust)"]:::runtime
        Relay["Mithril Relay\n(Rust P2P)"]:::runtime
        Aggregator["Mithril Aggregator\n(Rust HTTP)"]:::runtime
    end

    subgraph "Clients"
        CLI["CLI Client\n(Rust)"]:::client
        WASM["WASM Client\n(JS/WASM)"]:::client
        RustLib["Library Client\n(Rust)"]:::client
        Explorer["Explorer Frontend\n(Next.js/React)"]:::client
    end

    subgraph "Persistence & Storage"
        PersistenceLib["Persistence Layer\n(SQLite)"]:::persistence
        PersistenceDB["SQLite DB"]:::persistence
        FileUploader["File Uploader\n(GCP/local)"]:::runtime
    end

    subgraph "Shared Libraries"
        SharedCommon["mithril-common"]:::lib
        SharedStm["mithril-stm"]:::lib
    end

    %% Interactions
    Cardano -->|"fetch chain data"| Signer
    Cardano -->|"fetch chain data"| Aggregator
    Signer -->|"RegisterSignature Msg"| Relay
    Relay -->|"forward Msg"| Aggregator
    Aggregator -->|"store messages"| PersistenceLib
    PersistenceLib --> PersistenceDB
    Aggregator -->|"upload artifacts"| FileUploader
    FileUploader --> CloudStorage
    CLI -->|"GET /artifacts"| Aggregator
    WASM -->|"GET /artifacts"| Aggregator
    RustLib -->|"GET /artifacts"| Aggregator
    Explorer -->|"GET /artifacts"| Aggregator
    CLI -->|"verify proofs"| SharedStm
    WASM -->|"verify proofs"| SharedStm
    RustLib -->|"verify proofs"| SharedStm

    Infra -->|deploy| Cardano
    Infra -->|deploy| Signer
    Infra -->|deploy| Relay
    Infra -->|deploy| Aggregator
    Infra -->|deploy| Explorer

    TestLab -->|spins up stack| Cardano
    TestLab -->|spins up stack| Signer
    TestLab -->|spins up stack| Relay
    TestLab -->|spins up stack| Aggregator
    TestLab -->|runs tests| CLI

    %% Click Events
    click Signer "https://github.com/input-output-hk/mithril/tree/main/mithril-signer/"
    click Relay "https://github.com/input-output-hk/mithril/tree/main/mithril-relay/"
    click Aggregator "https://github.com/input-output-hk/mithril/tree/main/mithril-aggregator/"
    click CLI "https://github.com/input-output-hk/mithril/tree/main/mithril-client-cli/"
    click WASM "https://github.com/input-output-hk/mithril/tree/main/mithril-client-wasm/"
    click RustLib "https://github.com/input-output-hk/mithril/tree/main/mithril-client/"
    click SharedCommon "https://github.com/input-output-hk/mithril/tree/main/mithril-common/"
    click SharedStm "https://github.com/input-output-hk/mithril/tree/main/mithril-stm/"
    click PersistenceLib "https://github.com/input-output-hk/mithril/tree/main/internal/mithril-persistence/"
    click Infra "https://github.com/input-output-hk/mithril/tree/main/mithril-infra/"
    click Explorer "https://github.com/input-output-hk/mithril/tree/main/mithril-explorer/"
    click TestLab "https://github.com/input-output-hk/mithril/tree/main/mithril-test-lab/"
    click FileUploader "https://github.com/input-output-hk/mithril/blob/main/mithril-aggregator/src/services/file_uploader.rs"
    click Cardano "https://github.com/input-output-hk/mithril/tree/main/demo/"
    click Infra "https://github.com/input-output-hk/mithril/tree/main/mithril-infra/"
    click PersistenceDB "https://github.com/input-output-hk/mithril/tree/main/internal/mithril-persistence/"
    click Explorer "https://github.com/input-output-hk/mithril/tree/main/mithril-explorer/"

    %% Styles
    classDef runtime fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px
    classDef client fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef infra fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef lib fill:#eceff1,stroke:#607d8b,stroke-width:2px
    classDef persistence fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    classDef external fill:#fafafa,stroke:#9e9e9e,stroke-width:2px,stroke-dasharray: 5 5
```
