# cardano-scaling/hydra architecture

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

- Interactive diagram: https://gitdiagram.com/cardano-scaling/hydra
- Repository: https://github.com/cardano-scaling/hydra

## Overview

a. Hydra Node: This is the core protocol implementation (found in the “hydra-node” directory) and is responsible for running a coordinated Hydra Head.
b. API Layer: Represent the incoming connections via WebSocket/HTTP (as mentioned in the README and implemented across several submodules such as in hydra-node/src/Hydra/API).
c. Blockchain Interface: Capture the integration with the Cardano blockchain. This includes the APIs to Cardano implemented in “hydra-cardano-api” and connections like Direct TCP interactions.
d. Supporting Components/Tools:
- Hydra Chain Observer: For tracking and reacting to blockchain events.
- Hydra Cluster: Handling multi-node coordination in a clustered environment.
- Hydra TUI: The terminal user interface that acts as a client interface.
- Hydra Tx & Hydra Plutus: Modules dedicated to transaction construction and Plutus contract support.
- Demo and docs: Include these as external aids and examples rather than core live components, but they are valuable for testing and demonstration.
e. External Systems: Include Cardano nodes, external configuration and orchestration systems (Docker, Nix, AWS/GCP setups as seen in various sample configs).

##### Out the relationships and interactions
- Bi-directional communication between hydra-node and the Cardano blockchain (via hydra-cardano-api) that ensures transaction handling and state updates.
- Inter-node communications over direct TCP connections – explicitly note that the network is statically configured.
- If possible, detail the flow of a typical transaction lifecycle: From the client (committing a transaction) through the API and head state management, out to the blockchain, and then back through the chain observer.

##### Architectural patterns and design principles
- Separation of concerns: The system splits responsibilities amongst dedicated modules (e.g., node coordination, API handling, blockchain interaction, and transaction verification).
- Reactive/Asynchronous Processing: The protocol’s interactions are event-driven (noted in ADRs and in the modular API design for event streaming).
- Modularity and Extensibility: Multiple sub-projects (hydra-node, hydra-cluster, hydra-tx, hydra-plutus) indicate a service-oriented design where each component is individually testable and scalable.

##### Incorporate technical stack details
- Technologies: Haskell is the primary language (as indicated by .cabal files, .hs files, and references to “hydra-prelude”), with additional tooling for Docker and Nix.
- External Dependencies: Cardano node integration (via direct TCP) and the use of APIs and WebSockets for client communication.
- Testing and simulations: Note the demo and test directories which emphasize robust testing practices and potential simulation of network conditions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        TUI["Hydra TUI (Client Interface)"]:::client
    end

    subgraph "API Layer"
        API["API Layer (WebSocket/HTTP)"]:::api
    end

    subgraph "Core Protocol"
        NODE["Hydra Node (Core Protocol)"]:::core
        CLUSTER["Hydra Cluster (Multi-node Coordination)"]:::core
        TX["Hydra Tx (Transaction Construction)"]:::module
        PLUTUS["Hydra Plutus (Plutus Contract Support)"]:::module
    end

    subgraph "Blockchain & Observer"
        BLOCK["Blockchain Interface (Cardano API Connector)"]:::blockchain
        OBS["Hydra Chain Observer"]:::observer
    end

    subgraph "External Systems"
        CARDANO["Cardano Node"]:::external
        DEPLOY["Docker & Nix Deployment"]:::external
    end

    TUI -->|"HTTP/WebSocket"| API
    API -->|"InternalAPI"| NODE
    NODE -->|"DirectTCP"| CLUSTER
    NODE -->|"TxRequest"| TX
    NODE -->|"ContractCall"| PLUTUS
    NODE -->|"SendTransaction"| BLOCK
    BLOCK <-->|"Bidirectional"| CARDANO
    BLOCK -->|"EventUpdates"| OBS
    OBS -->|"UpdateState"| NODE
    DEPLOY --- NODE

    classDef client fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
    classDef api fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef blockchain fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef observer fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
    classDef external fill:#ede7f6,stroke:#5e35b1,stroke-width:2px;
    classDef module fill:#f0f4c3,stroke:#afb42b,stroke-width:2px;

    click NODE "https://github.com/cardano-scaling/hydra/tree/master/hydra-node"
    click API "https://github.com/cardano-scaling/hydra/tree/master/hydra-node/src/Hydra/API"
    click BLOCK "https://github.com/cardano-scaling/hydra/tree/master/hydra-cardano-api"
    click OBS "https://github.com/cardano-scaling/hydra/tree/master/hydra-chain-observer"
    click CLUSTER "https://github.com/cardano-scaling/hydra/tree/master/hydra-cluster"
    click TUI "https://github.com/cardano-scaling/hydra/tree/master/hydra-tui"
    click TX "https://github.com/cardano-scaling/hydra/tree/master/hydra-tx"
    click PLUTUS "https://github.com/cardano-scaling/hydra/tree/master/hydra-plutus"
```
