# exuralabs/hecate architecture

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

- Interactive diagram: https://gitdiagram.com/exuralabs/hecate
- Repository: https://github.com/exuralabs/hecate

## Overview

##### Project Type and Purpose
- Hecate is a full-stack data relay service for the Cardano blockchain.
- It connects to an Ogmios-enabled Cardano node, orchestrates historical and real-time data fetches, and forwards that data to downstream systems via Redis or a CLI interface.
- Key use cases: parallel historical syncing, real-time block relay, reorg detection, and optional metrics via Prefect.

##### File Structure Analysis
- client/ – asynchronous Ogmios WebSocket client and chain/ledger state helpers.
- flows/ – Prefect flow definitions: historical.py, periodic.py; checkpoint.json for dynamic epoch tracking.
- sinks/ – output modules: redis.py and cli.py implementing a common BaseSink interface.
- data/ & constants.py – static CSVs and configuration used by flows.
- models.py – Pydantic or dataclass definitions for message payloads.
- demo.py – ad-hoc script showcasing client capabilities.
- Prefect configuration (prefect.yaml) and project metadata (pyproject.toml).

##### README Insights
- Emphasis on Prefect for orchestration and Redis/CLI sinks.
- Notes on optional dependencies and deployment.

##### Detailed Checklist for the Engineer
- Component name exactly as in the code (client/, flows/, sinks/).
- Prefect server/agent separately if used.
- Static data sources (data/epoch_blocks.csv) feeding periodic tasks.
- Reorg detection as a sub-flow or callback loop.
- Concurrency: multiple workers for HistoricalSync.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        Node["Cardano Node + Ogmios"]:::external
        PrefectServer["Prefect Server/Agent"]:::orchestration
    end

    %% Async Client Layer
    subgraph "Async Client"
        AClient["Async Ogmios Client"]:::client
        Base["Client Base & Helpers"]:::client
        CI["Find Intersection"]:::client
        NB["Next Block Fetch"]:::client
        Epoch["Epoch Helper"]:::client
        Era["Era Summaries Helper"]:::client
        Tip["Tip Helper"]:::client
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        Constants["Configuration Constants"]:::support
        Models["Message Payload Models"]:::support
    end

    %% Static Data Sources
    subgraph "Static Data Sources"
        CSV1["epoch_blocks.csv"]:::support
        CSV2["epoch_boundaries.csv"]:::support
    end

    %% Core Processing Layer
    subgraph "Core Processing (Prefect Flows)"
        Hist["HistoricalSync Flow"]:::orchestration
        Periodic["PeriodicTasks Flow"]:::orchestration
        Checkpoint["Checkpoint Tracking"]:::orchestration
    end

    %% Data Sinks Layer
    subgraph "Data Sinks"
        BaseSink["BaseSink Interface"]:::sink
        Redis["Redis Sink"]:::sink
        CLI["CLI Sink"]:::sink
    end

    %% Downstream Applications
    subgraph "External Downstream"
        Downstream["Downstream Applications"]:::external
    end

    %% Connections
    Node -->|"WebSocket"| AClient
    AClient --> Base
    AClient --> CI
    AClient --> NB
    AClient --> Epoch
    AClient --> Era
    AClient --> Tip
    AClient -->|"Stream Data & Control"| PrefectServer

    PrefectServer --> Hist
    PrefectServer --> Periodic

    Hist -->|"BlockStream/Concurrent Batches"| Redis
    Hist -->|"CLI Fallback"| CLI
    Periodic --> Redis
    Periodic --> CLI
    Periodic -->|"uses"| Constants
    Periodic -->|"uses"| Models
    Periodic -->|"reads"| CSV1
    Periodic -->|"reads"| CSV2

    Checkpoint -.-> Hist

    Hist -->|"ReorgAlert"| AClient

    Redis -->|"Pub/Sub"| Downstream
    CLI -.->|"Output"| Downstream

    %% Click Events
    click AClient "https://github.com/exuralabs/hecate/blob/master/client/client.py"
    click Base "https://github.com/exuralabs/hecate/blob/master/client/base.py"
    click CI "https://github.com/exuralabs/hecate/blob/master/client/chainsync/find_intersection.py"
    click NB "https://github.com/exuralabs/hecate/blob/master/client/chainsync/next_block.py"
    click Epoch "https://github.com/exuralabs/hecate/blob/master/client/ledgerstate/epoch.py"
    click Era "https://github.com/exuralabs/hecate/blob/master/client/ledgerstate/era_summaries.py"
    click Tip "https://github.com/exuralabs/hecate/blob/master/client/ledgerstate/tip.py"
    click Hist "https://github.com/exuralabs/hecate/blob/master/flows/historical.py"
    click Periodic "https://github.com/exuralabs/hecate/blob/master/flows/periodic.py"
    click Checkpoint "https://github.com/exuralabs/hecate/blob/master/flows/checkpoint.json"
    click BaseSink "https://github.com/exuralabs/hecate/blob/master/sinks/base.py"
    click Redis "https://github.com/exuralabs/hecate/blob/master/sinks/redis.py"
    click CLI "https://github.com/exuralabs/hecate/blob/master/sinks/cli.py"
    click CSV1 "https://github.com/exuralabs/hecate/blob/master/data/epoch_blocks.csv"
    click CSV2 "https://github.com/exuralabs/hecate/blob/master/data/epoch_boundaries.csv"
    click Constants "https://github.com/exuralabs/hecate/blob/master/constants.py"
    click Models "https://github.com/exuralabs/hecate/blob/master/models.py"
    click PrefectServer "https://github.com/exuralabs/hecate/blob/master/prefect.yaml"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#005B96;
    classDef orchestration fill:#DFF2BF,stroke:#4F8A10;
    classDef sink fill:#FFEBAE,stroke:#FF8C00;
    classDef external fill:#E0E0E0,stroke:#888888;
    classDef support fill:#F0F0F0,stroke:#666666;
```
