# blazarlabs-io/blazar-hydra architecture

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

- Interactive diagram: https://gitdiagram.com/blazarlabs-io/blazar-hydra
- Repository: https://github.com/blazarlabs-io/blazar-hydra

## Overview

##### Project type and purpose
- Type: A Node.js/TypeScript-based backend service that exposes an HTTP API for managing Cardano/Hydra payment channels (“heads”)
- Purpose: Receive API calls (open head, deposit, pay, withdraw, close head), orchestrate off-chain transaction construction/submission, persist state, and deploy/validate on-chain smart contracts written in Aiken

##### File structure
- src/api – HTTP entry-points (server.ts, routes.ts), request validation (zod schemas), middleware (request-ID injection)
- src/offchain – Handlers (business workflows), tx-builders (Cardano transactions), utility libs (type definitions, Hydra helpers), a simple demo test
- src/onchain/hydra-pay – Aiken smart contract code and workflows (validators, types, utils) with CI
- src/prisma – Prisma ORM setup and embedded SQLite dev DB
- src/shared – Shared TypeScript types and Prisma schema definitions
- config.ts + logger/ – Global config and Pino logger abstraction

##### Main components and interactions
a. API Server
– Exposes REST endpoints via entry-points/routes.ts
– Validates with zod schemas and adds request IDs via middleware
– Injects config and logger
b. Off-chain Engine
– Handlers receive calls from API layer
– Use tx-builders to construct Cardano transactions (deposit, pay, merge funds, withdraw)
– Use Hydra library (hydra.ts) to manage head protocol messages
– Submit transactions to a Cardano node (RPC endpoint)
– Persist head state and transaction metadata via Prisma ORM
c. On-chain Validators
– Aiken language contracts in src/onchain/hydra-pay/validators
– Deployed via CLI or CI workflow
– Validate UTXOs according to Hydra-Pay logic
d. Database (Prisma)
– Schema stores user balances, head session info, tx history
– Generates a SQLite dev DB / can swap to Postgres in prod
e. External Services
– Cardano node / network (for submitting and confirming txs)
– Hydra network peers (for head messaging)

##### Architectural patterns and design principles
- Separation of concerns: Clear layers—API entrypoints, application logic (handlers), domain/Tx-builder libs, infrastructure (DB, network)
- Hexagonal/Ports & Adapters style: API and on-chain are adapters; off-chain lib is the core
- Schema-driven validation: zod for runtime type safety
- Sidecar DI: config.ts and logger definitions injected into modules
- Stateless handlers: Each handler builds a fresh tx, submits it, updates DB

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Server" 
        direction TB
        API_INDEX["src/api/index.ts"]:::api
        API_SERVER["server.ts"]:::api
        API_ROUTES["routes.ts"]:::api
        API_MW["request-id-middleware.ts"]:::api
        API_SCHEMAS["zod schemas"]:::api
    end

    %% Off-chain Layer
    subgraph "Off-chain Engine"
        direction TB
        OC_INDEX["src/offchain/index.ts"]:::offchain
        subgraph Handlers
            direction TB
            OC_OPEN["open-head.ts"]:::offchain
            OC_DEPOSIT["deposit.ts"]:::offchain
            OC_PAY["pay-merchant.ts"]:::offchain
            OC_WITHDRAW["withdraw.ts"]:::offchain
            OC_CLOSE["close-head.ts"]:::offchain
            OC_QUERY["query-funds.ts"]:::offchain
            OC_DEPLOY_VAL["deploy-validator.ts"]:::offchain
        end
        subgraph "Tx-Builders"
            direction TB
            TB_COMMIT["commit-funds.ts"]:::offchain
            TB_DEP["deposit.ts"]:::offchain
            TB_MERGE["merge-funds.ts"]:::offchain
            TB_PAY["pay.ts"]:::offchain
            TB_WM["withdrawMerchant.ts"]:::offchain
            TB_WU["withdrawUser.ts"]:::offchain
        end
        subgraph Libs
            direction TB
            LIB_HYDRA["hydra.ts"]:::offchain
            LIB_PARAMS["params.ts"]:::offchain
            LIB_TYPES["types.ts"]:::offchain
            LIB_UTILS["utils.ts"]:::offchain
        end
    end

    %% On-chain Layer
    subgraph "On-chain Validators"
        direction TB
        AK_MAIN["main.ak"]:::onchain
        AK_CHECKS["checks.ak"]:::onchain
        AK_TYPES["types.ak"]:::onchain
        AK_UTILS["utils.ak"]:::onchain
        PLUTUS["plutus.json"]:::onchain
    end
    CI["continuous-integration.yml"]:::onchain

    %% Database
    DB[(Prisma DB)]:::db
    PRISMA_SCHEMA["schema.prisma"]:::db
    DEV_DB["dev.db"]:::db
    SHARED_PRISMA["prisma-schemas.ts"]:::db

    %% Shared & Config
    subgraph "Shared & Config"
        direction TB
        SHARED_TYPES["types.ts"]:::shared
        SHARED_INDEX["index.ts"]:::shared
        CONFIG["config.ts"]:::shared
        LOG_DEF["definition.ts"]:::shared
        LOG_INDEX["index.ts"]:::shared
        LOG_PINO["pino.logger.ts"]:::shared
    end

    %% External Systems
    Cardano["Cardano Node"]:::external
    HydraPeers["Hydra Peers"]:::external

    %% Connections
    Client["Client"]:::external -->|"HTTP Request"| API_SERVER
    API_SERVER -->|"Route Handling"| API_ROUTES
    API_ROUTES -->|"Validate & ID"| API_MW
    API_ROUTES -->|"Schema Validation"| API_SCHEMAS
    API_ROUTES -->|"Invoke Handlers"| OC_INDEX
    OC_INDEX -->|Calls Handlers| OC_OPEN & OC_DEPOSIT & OC_PAY & OC_WITHDRAW & OC_CLOSE & OC_QUERY & OC_DEPLOY_VAL
    OC_OPEN & OC_DEPOSIT & OC_PAY & OC_WITHDRAW & OC_CLOSE & OC_QUERY & OC_DEPLOY_VAL -->|Use Builders| TB_COMMIT & TB_DEP & TB_MERGE & TB_PAY & TB_WM & TB_WU
    OC_OPEN & OC_DEPOSIT & OC_PAY & OC_WITHDRAW & OC_CLOSE & OC_QUERY & OC_DEPLOY_VAL -->|Use Hydra| LIB_HYDRA
    TB_COMMIT & TB_DEP & TB_MERGE & TB_PAY & TB_WM & TB_WU -->|"Build & Submit Tx"| Cardano
    OC_OPEN & OC_DEPOSIT & OC_PAY & OC_WITHDRAW & OC_CLOSE & OC_QUERY & OC_DEPLOY_VAL -->|"Read/Write State"| PRISMA_SCHEMA & DEV_DB
    OC_OPEN & OC_DEPOSIT & OC_PAY & OC_WITHDRAW & OC_CLOSE & OC_QUERY & OC_DEPLOY_VAL -->|"Use Types"| LIB_TYPES
    OC_OPEN & OC_DEPOSIT & OC_PAY & OC_WITHDRAW & OC_CLOSE & OC_QUERY & OC_DEPLOY_VAL -->|"Use Params/Utils"| LIB_PARAMS & LIB_UTILS
    CI -->|"Compile & Deploy"| AK_MAIN & AK_CHECKS & AK_TYPES & AK_UTILS & PLUTUS
    AK_MAIN & AK_CHECKS & AK_TYPES & AK_UTILS & PLUTUS -->|On-chain Validation| Cardano
    SHARED_TYPES & SHARED_INDEX -->|"Shared Schemas"| API_SCHEMAS & OC_INDEX
    CONFIG -->|"Inject Config"| API_INDEX & OC_INDEX
    LOG_DEF & LOG_INDEX & LOG_PINO -->|"Provide Logger"| API_INDEX & OC_INDEX

    %% Click Events
    click API_INDEX "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/api/index.ts"
    click API_SERVER "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/api/entry-points/server.ts"
    click API_ROUTES "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/api/entry-points/routes.ts"
    click API_MW "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/api/middleware/request-id-middleware.ts"
    click API_SCHEMAS "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/api/schemas/zod.ts"
    click OC_INDEX "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/index.ts"
    click OC_OPEN "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/handlers/open-head.ts"
    click OC_DEPOSIT "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/handlers/deposit.ts"
    click OC_PAY "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/handlers/pay-merchant.ts"
    click OC_WITHDRAW "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/handlers/withdraw.ts"
    click OC_CLOSE "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/handlers/close-head.ts"
    click OC_QUERY "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/handlers/query-funds.ts"
    click OC_DEPLOY_VAL "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/handlers/deploy-validator.ts"
    click TB_COMMIT "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/tx-builders/commit-funds.ts"
    click TB_DEP "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/tx-builders/deposit.ts"
    click TB_MERGE "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/tx-builders/merge-funds.ts"
    click TB_PAY "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/tx-builders/pay.ts"
    click TB_WM "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/tx-builders/withdrawMerchant.ts"
    click TB_WU "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/tx-builders/withdrawUser.ts"
    click LIB_HYDRA "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/lib/hydra.ts"
    click LIB_PARAMS "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/lib/params.ts"
    click LIB_TYPES "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/lib/types.ts"
    click LIB_UTILS "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/offchain/lib/utils.ts"
    click AK_MAIN "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/onchain/hydra-pay/validators/main.ak"
    click AK_CHECKS "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/onchain/hydra-pay/lib/checks.ak"
    click AK_TYPES "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/onchain/hydra-pay/lib/types.ak"
    click AK_UTILS "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/onchain/hydra-pay/lib/utils.ak"
    click PLUTUS "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/onchain/hydra-pay/plutus.json"
    click CI "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/onchain/hydra-pay/.github/workflows/continuous-integration.yml"
    click PRISMA_SCHEMA "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/prisma/schema.prisma"
    click DEV_DB "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/prisma/prisma/dev.db"
    click SHARED_PRISMA "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/shared/prisma-schemas.ts"
    click SHARED_TYPES "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/shared/types.ts"
    click SHARED_INDEX "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/shared/index.ts"
    click CONFIG "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/config.ts"
    click LOG_DEF "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/logger/definition.ts"
    click LOG_INDEX "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/logger/index.ts"
    click LOG_PINO "https://github.com/blazarlabs-io/blazar-hydra/blob/main/src/logger/pino.logger.ts"

    %% Styles
    classDef api fill:#cce5ff,stroke:#003366,color:#003366;
    classDef offchain fill:#d4edda,stroke:#155724,color:#155724;
    classDef onchain fill:#fff3cd,stroke:#856404,color:#856404;
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f5d0f0,stroke:#6f42c1,color:#6f42c1;
    classDef shared fill:#f0f0f0,stroke:#333333,color:#333333;
```
