# anastasia-labs/midgard architecture

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

- Interactive diagram: https://gitdiagram.com/anastasia-labs/midgard
- Repository: https://github.com/anastasia-labs/midgard

## Overview

##### Main Components
- Onchain Layer:
- “onchain/aiken”: Contains the onchain smart contract code written in Aiken. This is where the core protocol logic, validators, and smart contract definitions reside.
- “onchain/plutarch”: Contains Haskell/Plutarch code that likely implements additional onchain functionality (e.g., advanced validation, helper libraries, cryptographic functions).
- The Aiken and Plutarch components together represent the onchain execution environment that enforces protocol rules on Cardano.

- Offchain/Supporting Layers:
- Midgard Manager and CLI Tools:
· Located under “demo/midgard-manager” with packages such as “cli” and “tx-generator”. These provide command-line interfaces, interactive tools, and transaction generation utilities.
· They orchestrate configuration, wallet interactions, and transaction scheduling.
- Midgard Node:
· Under “demo/midgard-node” contains service files, database modules, worker processes, Docker deployment files, and monitoring configurations (Prometheus, Grafana, Loki). This is the heart of the offchain orchestration, managing state queues, mempool, DB records, and interacting with the blockchain network.
- Midgard SDK:
· Found in “demo/midgard-sdk”. It contains endpoints (for hub-oracle, state-queue, and tx-builder), a client abstraction layer, and utility functions. This SDK enables external clients or services to interact with the protocol smoothly.

- External and Supporting Components:
- Developer documentation (“documentation” folder): Contains the code and configuration for the documentation website (likely a Next.js/React app) that provides an overview and additional architectural decision records.
- Continuous integration and deployment files (GitHub workflows, Makefiles, Dockerfiles) indicate that automated testing, building, and deployment pipelines are an integral part of the project.

##### Component Relationships & Interactions
- The onchain code (Aiken/Plutarch) serves as the immutable execution engine where validators and protocol rules live. This layer interacts with offchain components through transaction submissions.
- The Midgard Node is responsible for interfacing with the blockchain: it reads data from the chain (blocks, state queues) and processes transactions according to the protocol’s state machine. It also pushes data into the database and leverages worker modules for asynchronous processing.
- The CLI tools and Transaction Generator (part of midgard-manager and tx-generator) interact with both the node and the onchain network, providing an interactive, developer-friendly interface for crafting transactions and testing protocol operations.
- The SDK acts as a bridge for developers building on top of Midgard, enabling them to call endpoints (for example, fetching ledger state or scheduling transactions) while abstracting away lower-level protocol details.

##### Important Architectural Patterns & Design Principles
- Separation of concerns: Onchain logic (immutable, consensus-critical smart contracts) is clearly separated from offchain services (transaction generation, state tracking, and developer tools).
- Modularity and extensibility: With separate packages (CLI, SDK, tx-generator), each component can be maintained, tested, and even replaced independently.
- Use of containerization and continuous integration: Dockerfiles, GitHub workflows, and Makefiles suggest an emphasis on deployment automation and consistent environments.
- Data flow orchestration: Components such as state queues, scheduler modules (both in the midgard-node and SDK portions) show a well-thought-out pipeline for processing transactions and coordinating between onchain and offchain layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Onchain Layer"
        Aiken["Aiken Smart Contracts"]:::onchain
        Plutarch["Plutarch Modules"]:::onchain
    end

    subgraph "Offchain Layer"
        CLI["CLI & TX Generator (Manager)"]:::offchain
        Node["Midgard Node"]:::offchain
        SDK["Midgard SDK"]:::offchain
    end

    subgraph "Documentation"
        TechSpec["Technical Specification"]:::docs
        DevDocs["Developer Documentation"]:::docs
    end

    subgraph "Monitoring & Deployment"
        Infra["Monitoring & Deployment Infrastructure"]:::infra
    end

    CLI -->|"submitsTx"| Node
    Node -->|"executesTx"| Aiken
    Node -->|"executesTx"| Plutarch
    SDK <-->|"biDirectional"| Node
    Node -->|"monitoringData"| Infra

    click Aiken "https://github.com/anastasia-labs/midgard/tree/main/onchain/aiken"
    click Plutarch "https://github.com/anastasia-labs/midgard/tree/main/onchain/plutarch"
    click CLI "https://github.com/anastasia-labs/midgard/tree/main/demo/midgard-manager"
    click Node "https://github.com/anastasia-labs/midgard/tree/main/demo/midgard-node"
    click SDK "https://github.com/anastasia-labs/midgard/tree/main/demo/midgard-sdk"
    click TechSpec "https://github.com/anastasia-labs/midgard/tree/main/technical-spec"
    click DevDocs "https://github.com/anastasia-labs/midgard/tree/main/documentation"
    click Infra "https://github.com/anastasia-labs/midgard/tree/main/demo/midgard-node"

    classDef onchain fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
    classDef offchain fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef docs fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef infra fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
```
