# eodata/operator-setup architecture

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

- Interactive diagram: https://gitdiagram.com/eodata/operator-setup
- Repository: https://github.com/eodata/operator-setup

## Overview

##### Project type and purpose
- This is a container-orchestration “operator-setup” toolkit for running and monitoring an EO AVS data-validator.
- It combines a CLI wrapper (run.sh) around Docker Compose recipes for two sets of services:
– The EO data-validator microservice
– A Prometheus-Grafana-Node-Exporter-VMAgent monitoring stack

##### File structure
- Root:
– run.sh: shell wrapper to generate keys, encrypt, register/deregister on the blockchain, and launch containers
– README.md: operator setup guide, CLI commands, docker steps, monitoring setup
- data-validator/
– .example_env, .example_env_holesky → environment variable templates for the validator
– docker-compose.yml → defines the validator container and its dependencies (ports, volumes)
– dashboards/ → Grafana JSON dashboard definitions for validator and node-exporter
– monitoring/ → nested docker-compose.yml plus configuration for Prometheus, Grafana, VMAgent, Node-Exporter
- Key patterns:
– Docker Compose for grouping related containers
– Separate Compose files for “validator” and “monitoring” stacks
– Environment-driven configuration via .env files

##### Extract architectural insights from the README
- The “run.sh” scripts wrap calls to: generate/encrypt keys, invoke EO CLI, spin up/down containers
- Data-validator exposes:
– HTTP health endpoints (port 9000)
– Prometheus metrics (port 9100)
– Data port (9200, V2)
– Subscribes to external WS feeds (Coinbase, Bybit, BitMart, Gate.io)
– Posts signed transactions to the EO chain RPC endpoint
- Monitoring stack:
– Prometheus scrapes validator metrics and Node-Exporter
– Grafana reads from Prometheus (datasource on port 9090) and offers prebuilt dashboards
– VMAgent optionally aggregates and forwards metrics

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Control Plane" 
        direction TB
        CLI["run.sh CLI"]:::cli
        EnvTemplates[".env Templates"]:::storage
        Keystore["Keystore Volume"]:::storage
        CLI -->|"loads"| EnvTemplates
        CLI -->|"generates"| Keystore
        click CLI "https://github.com/eodata/operator-setup/blob/main/run.sh"
        click EnvTemplates "https://github.com/eodata/operator-setup/blob/main/data-validator/.example_env"
        click EnvTemplates "https://github.com/eodata/operator-setup/blob/main/data-validator/.example_env_holesky"
    end

    %% Validator Stack
    subgraph "Validator Stack" 
        direction TB
        VCCompose["Validator Docker Compose"]:::compose
        Validator["EO Data Validator"]:::validator
        Health["HTTP 9000"]:::port
        Metrics["Prometheus 9100"]:::port
        DataPort["Data V2 9200"]:::port
        VCCompose --> Validator
        Validator -->|"/health (HTTP)"| Health
        Validator -->|"/metrics (Prometheus)"| Metrics
        Validator -->|"Data V2"| DataPort
        Validator -->|"WS Feeds (Coinbase,Bybit,BitMart,Gate.io)"| WS["WebSocket Feeds"]:::external
        Validator -->|"RPC (EO Chain)"| RPC["EO Chain RPC"]:::external
        click VCCompose "https://github.com/eodata/operator-setup/blob/main/data-validator/docker-compose.yml"
    end

    %% Monitoring Stack
    subgraph "Monitoring Stack"
        direction TB
        MCCompose["Monitoring Docker Compose"]:::compose
        Prometheus["Prometheus"]:::monitor
        Grafana["Grafana"]:::monitor
        NodeExp["Node Exporter"]:::monitor
        VMAgent["VMAgent"]:::monitor
        Dashboards["Grafana Dashboards"]:::storage
        PMC["prometheus.yml"]:::config
        GDC["datasource.yml"]:::config
        VMC["vmagent.yml"]:::config
        MReadme["Monitoring README"]:::docs

        MCCompose --> Prometheus
        MCCompose --> Grafana
        MCCompose --> NodeExp
        MCCompose --> VMAgent

        Prometheus -->|scrapes| Metrics
        Prometheus -->|scrapes| NodeExp
        VMAgent -->|scrapes/forwards| Prometheus
        Grafana -->|queries| Prometheus
        Dashboards --> Grafana

        click MCCompose "https://github.com/eodata/operator-setup/blob/main/data-validator/monitoring/docker-compose.yml"
        click PMC "https://github.com/eodata/operator-setup/blob/main/data-validator/monitoring/prometheus.yml"
        click GDC "https://github.com/eodata/operator-setup/blob/main/data-validator/monitoring/grafana/datasource.yml"
        click VMC "https://github.com/eodata/operator-setup/blob/main/data-validator/monitoring/vmagent.yml"
        click MReadme "https://github.com/eodata/operator-setup/blob/main/data-validator/monitoring/README.md"
        click Dashboards "https://github.com/eodata/operator-setup/blob/main/data-validator/dashboards/data-validator.json"
        click Dashboards "https://github.com/eodata/operator-setup/blob/main/data-validator/dashboards/node-exporter.json"
    end

    %% CI/CD Registry
    Registry["Docker Registry"]:::external
    CLI -->|pull images| Registry

    %% README Link
    ProjectReadme["Project README"]:::docs
    click ProjectReadme "https://github.com/eodata/operator-setup/blob/main/README.md"

    %% Styles
    classDef cli fill:#AEDFF7,stroke:#0366d6,color:#0366d6;
    classDef validator fill:#C6E6FF,stroke:#1B4F72,color:#1B4F72;
    classDef compose fill:#E2E8F0,stroke:#4A5568,color:#4A5568;
    classDef monitor fill:#D4EDDA,stroke:#155724,color:#155724;
    classDef external fill:#F8D7DA,stroke:#721C24,color:#721C24;
    classDef storage fill:#FFF3CD,stroke:#856404,color:#856404;
    classDef port fill:#F0F9FF,stroke:#1E3A8A,color:#1E3A8A;
    classDef config fill:#E9ECEF,stroke:#6C757D,color:#6C757D;
    classDef docs fill:#E2E3E5,stroke:#4E555B,color:#4E555B;
```
