# madara-alliance/madara architecture

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

- Interactive diagram: https://gitdiagram.com/madara-alliance/madara
- Repository: https://github.com/madara-alliance/madara

## Overview

Based on our analysis of the file tree and README, this project appears to be a large, multi-component blockchain/node system (named “Madara”) that includes several lower-level libraries and clients (written in Rust and Cairo) along with an orchestrator component. In addition, there is a very modularized CI/CD system implemented through GitHub Actions workflows that enables builds, testing, linting, deployments, and integration verifications using custom actions (like load-env and rust-setup).

##### Main Components
- CI/CD & Workflow Engine: Represent the entire “.github” folder as the CI/CD engine. Break it into:
– Trigger Workflows (e.g. pull-request-main-ci.yml, push workflows)
– Task Workflows (files prefixed with “task-…” that encapsulate specific build or test steps)
– Scheduled Workflows (files prefixed with “schedule-…”)
– Custom Actions (e.g. load-env and rust-setup that set environment variables and configure the Rust toolchain)
- Node and Client Libraries (“madara” directory):
– Core Node: This is the runtime part (located in madara/crates/node) that includes command-line interfaces, block production, and service modules.
- Core Cryptography & Primitives: Display the “primitives” directory, which is further divided (block, class, chain_config, rpc, transactions, oracle, etc.). This layer encapsulates fundamental data formats, hash and crypto utilities, and conversion tools for both Starknet and Ethereum integrations.
- Orchestrator: Show a separate component drawn from the “orchestrator” directory. Outline submodules such as:
– CLI and configuration management that deal with alerts, da-clients (Ethereum and others), databases, queues (SQS, AWS), and proofs.
– Worker processes that handle data submission, proof registration, and state updates.
- Cairo Codebase: Represent the “cairo” directory with its source files, tests, and artifacts. This is likely responsible for on-chain contracts and related tooling in the Starknet ecosystem.
- Infrastructure & Deployment: Include deployment and containerization components:
– Dockerfiles (everywhere from the root Dockerfile to production-specific Dockerfiles in docker/ and infra/)
– Devcontainer configurations and compose files (e.g. compose.yaml) which hint at local development and testing provisions.
– Monitoring dashboards and configuration (Grafana, Prometheus, telegraf, etc. under infra/ and dashboards).

##### Relationships and Interactions
– The CI/CD engine (GitHub Actions workflows) triggers builds for the madara node, orchestrator, and helper libraries.
– Custom actions and scripts (load-env, rust-setup) provide an interface between configuration (env.yml) and build artifacts.
– The orchestrator communicates with core node libraries via API endpoints (covered by the RPC modules) and may use the clients (DA, Ethereum, etc.) to aggregate data.
– The primitives provide essential functions that are consumed by various client modules.
– External tools (like Docker, Act for local testing, and external Ethereum/Starknet RPC endpoints) integrate into several components.

##### Architectural Patterns and Technologies
- Separation of Concerns: Clearly label components (for instance, separating out primitives from the network clients and node core) to show clean architectural boundaries.
- GitHub Actions Patterns: Indicate how trigger workflows invoke reusable task workflows, and how environment settings from config files pass into the build and test pipelines.
- Technology Stacks: Label primary languages and frameworks – Rust for most back-end components, Cairo for contract-related code, and JavaScript/TypeScript for testing and some orchestration scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD & Workflow Engine
    subgraph "CI/CD & Workflow Engine"
        GitHubWorkflows["GitHub Workflows"]
    end

    %% Application Core Layer
    subgraph "Application Core"
        CoreNode["Core Node (Node Runtime)"]
        ClientSubsystems["Client Subsystems"]
        CorePrimitives["Core Cryptography & Primitives"]
    end

    %% Support Systems Layer
    subgraph "Support Systems"
        Orchestrator["Orchestrator"]
        subgraph "Infrastructure & Deployment"
            DockerCompose["Docker & Compose"]
            Devcontainer["Devcontainer"]
            Monitoring["Monitoring & Infra"]
        end
    end

    %% On-chain / Smart Contracts Layer
    subgraph "On-chain / Smart Contracts"
        CairoCodebase["Cairo Codebase"]
    end

    %% CI/CD triggers builds and deployments
    GitHubWorkflows -->|"triggers"| CoreNode
    GitHubWorkflows -->|"triggers"| Orchestrator
    GitHubWorkflows -->|"triggers"| CairoCodebase
    GitHubWorkflows -->|"deploys"| DockerCompose
    GitHubWorkflows -->|"deploys"| Devcontainer
    GitHubWorkflows -->|"deploys"| Monitoring

    %% Application Core internal dependencies
    CorePrimitives -->|"used-by"| ClientSubsystems
    ClientSubsystems -->|"integrates"| CoreNode

    %% Orchestrator calls Core Node via API/RPC
    Orchestrator -->|"calls_RPC"| CoreNode

    %% Styling Classes
    class GitHubWorkflows ci
    class CoreNode,ClientSubsystems,CorePrimitives core
    class Orchestrator,DockerCompose,Devcontainer,Monitoring support
    class CairoCodebase contracts

    %% Click Events for Component Mapping
    click GitHubWorkflows "https://github.com/madara-alliance/madara/blob/main/.github"
    click CoreNode "https://github.com/madara-alliance/madara/tree/main/madara/crates/node"
    click ClientSubsystems "https://github.com/madara-alliance/madara/tree/main/madara/crates/client"
    click CorePrimitives "https://github.com/madara-alliance/madara/tree/main/madara/crates/primitives"
    click Orchestrator "https://github.com/madara-alliance/madara/tree/main/orchestrator"
    click CairoCodebase "https://github.com/madara-alliance/madara/tree/main/cairo"
    click DockerCompose "https://github.com/madara-alliance/madara/tree/main/docker/"
    click Devcontainer "https://github.com/madara-alliance/madara/blob/main/.devcontainer"
    click Monitoring "https://github.com/madara-alliance/madara/tree/main/infra"
```
