# intersectmbo/cardano-node architecture

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

- Interactive diagram: https://gitdiagram.com/intersectmbo/cardano-node
- Repository: https://github.com/intersectmbo/cardano-node

## Overview

##### Main components
- Core Node Engine: This is the central component (cardano-node) that aggregates multiple sub‐systems.
- Ledger & Consensus Modules: These represent the Cardano ledger specifications and consensus algorithms (integrated from external repositories like cardano-ledger-specs and ouroboros-consensus).
- Networking: The networking infrastructure responsible for peer connections based on the topology files (described in the configuration and topology directories).
- Node Shell & CLI: The command-line interface and node shell components that manage logging and monitoring (referenced via cardano-shell and integrated logging modules).
- Configuration Management: Elements handling network configuration, genesis files, topology files, and other settings (as seen in the configuration folder and various YAML/JSON files).
- External Interfaces: Although wallet and explorer functionalities are now decoupled, they still interact with the node via IPC; also, external tools such as cardano-cli, cardano-submit-api, and test utilities interact with the node.
- Ancillary Tools & Scripts: Several benchmarking tools, transaction generators, and tracing/monitoring tools (e.g., cardano-tracer, trace-forward, trace-resources) that augment testing, monitoring, and operation of the node.

##### Relationships and interactions
- The Core Node Engine centrally orchestrates interactions between the consensus engine, ledger management, and networking interfaces.
- Configuration files (YAML/JSON) feed data into the node for initializing network parameters (e.g., genesis, topology) and logging options.
- The CLI and node shell provide user and operational interfaces to control the node’s behavior (including starting and stopping block production, signing key migration, and update proposal management).
- External processes, such as wallet backends and explorer nodes, interact with the node through local IPC mechanisms via defined socket paths.
- The logging and monitoring subsystems (using dedicated packages like io-hk monitoring framework) allow external visualization and tracing (served via cardano-tracer and related tools).

##### Important architectural patterns and principles
- Modular Aggregation: The node aggregates multiple independently developed components (consensus, ledger, networking) into a single runtime.
- Separation of Concerns: There is a clear delineation between core blockchain functionalities (ledger/consensus) and peripheral functionalities (CLI, logging, configuration). The decoupling of wallet/explorer functionality into separate processes further emphasizes this principle.
- Configuration-driven: Extensive use of configuration files (found in directories like configuration and defaults) to set parameters for networks (mainnet, testnet) and control node behavior.
- Dependency Injection via External Scripts: The repository depends on external scripts, benchmarking tools, and testing frameworks which are clearly scoped in their own directories, demonstrating a clean separation between production code and auxiliary tooling.

##### Relevant technologies and frameworks
- Haskell Compiler/Build Tools: The project is built using Cabal and GHC with additional tools like ghcid for live reloading.
- Networking & Consensus Libraries: Integration with external consensus and ledger libraries from IOHK (e.g., ouroboros-network, cardano-ledger-specs).
- Configuration Management: Usage of YAML and JSON formats for configuration files.
- Containerization: Docker support is provided via docker-compose and Dockerfiles.
- Nix/NixOS Integration: The repository includes Nix expressions and flake configuration to assist with reproducible builds and deployments.

- Clear labels for each component (e.g., “Core Node Engine”, “Consensus Module”, “Ledger Module”, “Networking”, “CLI / Node Shell”, “Configuration Management”, “Logging & Monitoring”, “External Interfaces”).
- Major interfaces like the use of sockets (for IPC), key signing/migration processes, and transaction submission mechanisms.

##### Additional details
- It is important to capture every high-level integration as seen in the repository. Even though there is a very large and organized file tree, focus on extracting the core modules and their interactions.
- Do not over-simplify; consider including separate nodes for benchmarking and testing utilities, as they are important for developers working on performance and correctness.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CoreNodeEngine["Core Node Engine"]:::core
    LedgerConsensus["Ledger & Consensus Modules"]:::core
    Networking["Networking"]:::core

    NodeShell["Node Shell & CLI"]:::external
    ExternalInterfaces["External Interfaces"]:::external
    LoggingMonitoring["Logging & Monitoring"]:::external

    ConfigMgmt["Configuration Management"]:::aux
    AncillaryTools["Ancillary Tools & Scripts"]:::aux

    ConfigMgmt -->|"feeds_config"| CoreNodeEngine
    ConfigMgmt -->|"configures_topology"| Networking
    CoreNodeEngine -->|"orchestrates"| LedgerConsensus
    CoreNodeEngine -->|"manages_connection"| Networking
    NodeShell -->|"controls"| CoreNodeEngine
    CoreNodeEngine <-->|"IPC"| ExternalInterfaces
    LoggingMonitoring -->|"monitors"| CoreNodeEngine
    AncillaryTools -->|"supports"| LoggingMonitoring
    AncillaryTools -->|"testing_benchmark"| CoreNodeEngine

    click CoreNodeEngine "https://github.com/intersectmbo/cardano-node/blob/master/cardano-node/app/cardano-node.hs"
    click CoreNodeEngine "https://github.com/intersectmbo/cardano-node/tree/master/cardano-node/src/Cardano/Node"
    
    click LedgerConsensus "https://github.com/intersectmbo/cardano-node/tree/master/cardano-node/src/Cardano/Node/Protocol"

    click Networking "https://github.com/intersectmbo/cardano-node/blob/master/cardano-node/src/Cardano/Node/Configuration/Topology.hs"
    click Networking "https://github.com/intersectmbo/cardano-node/blob/master/configuration/cardano/mainnet-topology.json"

    click NodeShell "https://github.com/intersectmbo/cardano-node/blob/master/cardano-node-chairman/app/cardano-node-chairman.hs"

    click ConfigMgmt "https://github.com/intersectmbo/cardano-node/tree/master/configuration/"

    click ExternalInterfaces "https://github.com/intersectmbo/cardano-node/blob/master/cardano-submit-api/app/Main.hs"
    click ExternalInterfaces "https://github.com/intersectmbo/cardano-node/tree/master/cardano-submit-api/src/Cardano/TxSubmit"

    click LoggingMonitoring "https://github.com/intersectmbo/cardano-node/tree/master/cardano-tracer/"

    click AncillaryTools "https://github.com/intersectmbo/cardano-node/tree/master/bench/"
    click AncillaryTools "https://github.com/intersectmbo/cardano-node/tree/master/scripts/"

    classDef core fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef external fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef aux fill:#f3722c,stroke:#000,stroke-width:2px;
```
