# web3tea/curio-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/web3tea/curio-dashboard
- Repository: https://github.com/web3tea/curio-dashboard

## Overview

##### Project Type & Purpose
- Full-stack web application for real-time monitoring and management of a Curio cluster.
- Frontend: Vue.js + TypeScript + Apollo GraphQL client.
- Backend: Go service exposing a GraphQL API (gqlgen), data loaders and subscriptions.

##### Main Components
A. Frontend
- Vue.js SPA (ui/) with Apollo Client for GraphQL queries/subscriptions.
- UI layers: layouts, views, components, stores, styling.

B. Backend GraphQL Server
- `cmd/` entrypoints orchestrating configuration, GraphQL server, caching, Prometheus integration.
- `graph/` contains schema definitions, generated code, resolvers, data loaders, cache-control extensions.
- `config/` holds configuration parsing.
- `db/` handles direct database logic (YugabyteDB).

C. Data Stores & Caches
- YugabyteDB (configured via `config.toml`) for cluster state and metadata.
- In-memory cache (per-resolver cachecontrol).
- Prometheus client for metrics ingestion (optional).

D. External Services
- Curio Web API (RPC) for cluster commands and real-time events.
- Lotus Daemon for blockchain data retrieval.
- Prometheus endpoint for time-series metrics.

E. Deployment & Tooling
- Docker (Dockerfile, ci.Dockerfile) for containerized builds.
- Makefile, CI workflows (.github/workflows) for build/test.
- .devcontainer for development environment.

##### Component Interactions
1. Frontend → GraphQL Server (HTTP/WebSocket)
- Queries & mutations to fetch and update cluster data.
- Subscriptions for real-time updates.
2. GraphQL Server → Data Loaders / Cache / DB
- Resolve GraphQL fields by batching calls, caching, or database queries.
3. GraphQL Server → External APIs
- Curio RPC client under `graph/curiorpc/` for tasks, machines, IPNI, miner info.
- Prometheus client under `graph/prometheus/`.
- Lotus RPC via configuration.
4. GraphQL Server → Database
- CRUD on cluster metadata, configuration, task history.
5. Database & Prometheus
- Persistent store and time-series metrics are independent backends.

##### Architectural Patterns & Principles
- GraphQL schema-first design with code generation (gqlgen).
- Resolver & loader layering for separation of concerns and batching.
- Modular frontend with Vue components, stores, and Apollo integration.
- Clear environment-based configuration and pluggable endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend" 
        SPA["Vue.js SPA"]:::frontend
        Apollo["Apollo GraphQL Client"]:::frontend
        Components["Vue Components"]:::frontend
        Views["Vue Views"]:::frontend
        Stores["Vue Stores"]:::frontend
        Plugins["Apollo Setup"]:::frontend
        Operations["GraphQL Operations"]:::frontend
        Router["Router Config"]:::frontend
        main["UI Entry (ui/src/main.ts)"]:::frontend
    end

    subgraph "GraphQL Server"
        Entrypoints["cmd/ (main.go, run.go, config.go)"]:::backend
        Config["config/config.go"]:::backend
        Handler["GraphQL Handler"]:::backend
        Schema["Schema Definitions"]:::backend
        Generated["Generated Types & Stubs"]:::backend
        Resolvers["Resolvers Implementation"]:::backend
        Loaders["Data Loaders"]:::backend
        CacheControl["Cache-Control Extensions"]:::backend
        CurioRPC["Curio RPC Client"]:::backend
        PrometheusInt["Prometheus Integration"]:::backend
        GQLGenCfg["gqlgen.yml"]:::backend
        DBLogic["DB Logic (YugabyteDB)"]:::backend
    end

    cyl1[(YugabyteDB)]:::database
    cyl2[(In-memory Cache)]:::database

    subgraph "External Services"
        CurioWS["Curio RPC (cluster API)"]:::external
        Lotus["Lotus Daemon"]:::external
        PromExt["Prometheus Endpoint"]:::external
    end

    subgraph "Deployment & Tooling"
        Docker["Dockerfiles"]:::tooling
        Make["Makefile"]:::tooling
        CI["CI Workflow"]:::tooling
        DevContainer["Dev Container"]:::tooling
    end

    %% Connections
    SPA -->|"HTTP/WebSocket"| Entrypoints
    Entrypoints -->|"start GraphQL Server"| Handler
    Handler -->|"uses Schema"| Schema
    Handler -->|"loads Types"| Generated
    Handler -->|"calls Resolvers"| Resolvers
    Resolvers -->|"batch via"| Loaders
    Loaders -->|"cache via"| CacheControl
    Loaders -->|"query"| DBLogic
    DBLogic -->|SQL| cyl1
    Handler -->|"cache lookup"| cyl2
    Handler -->|"RPC"| CurioRPC
    Handler -->|"RPC"| Lotus
    Handler -->|"HTTP"| PromExt

    %% Click Events
    click SPA "https://github.com/web3tea/curio-dashboard/tree/main/ui/"
    click Apollo "https://github.com/web3tea/curio-dashboard/blob/main/ui/src/plugins/apollo.ts"
    click Components "https://github.com/web3tea/curio-dashboard/tree/main/ui/src/components/"
    click Views "https://github.com/web3tea/curio-dashboard/tree/main/ui/src/views/"
    click Stores "https://github.com/web3tea/curio-dashboard/tree/main/ui/src/stores/"
    click Plugins "https://github.com/web3tea/curio-dashboard/blob/main/ui/src/plugins/apollo.ts"
    click Operations "https://github.com/web3tea/curio-dashboard/tree/main/ui/src/gql/"
    click Router "https://github.com/web3tea/curio-dashboard/tree/main/ui/src/router/"
    click main "https://github.com/web3tea/curio-dashboard/blob/main/ui/src/main.ts"
    click Entrypoints "https://github.com/web3tea/curio-dashboard/tree/main/cmd/"
    click Config "https://github.com/web3tea/curio-dashboard/blob/main/config/config.go"
    click Handler "https://github.com/web3tea/curio-dashboard/blob/main/graph/handler.go"
    click Schema "https://github.com/web3tea/curio-dashboard/tree/main/graph/schema/"
    click Generated "https://github.com/web3tea/curio-dashboard/blob/main/graph/generated.go"
    click Resolvers "https://github.com/web3tea/curio-dashboard/tree/main/graph/resolvers/"
    click Loaders "https://github.com/web3tea/curio-dashboard/tree/main/graph/loaders/"
    click CacheControl "https://github.com/web3tea/curio-dashboard/tree/main/graph/cachecontrol/"
    click CurioRPC "https://github.com/web3tea/curio-dashboard/tree/main/graph/curiorpc/"
    click PrometheusInt "https://github.com/web3tea/curio-dashboard/tree/main/graph/prometheus/"
    click GQLGenCfg "https://github.com/web3tea/curio-dashboard/blob/main/gqlgen.yml"
    click DBLogic "https://github.com/web3tea/curio-dashboard/blob/main/db/harmony.go"
    click Docker "https://github.com/web3tea/curio-dashboard/tree/main/Dockerfile"
    click Docker "https://github.com/web3tea/curio-dashboard/blob/main/ci.Dockerfile"
    click Make "https://github.com/web3tea/curio-dashboard/tree/main/Makefile"
    click CI "https://github.com/web3tea/curio-dashboard/blob/main/.github/workflows/ci.yml"
    click DevContainer "https://github.com/web3tea/curio-dashboard/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#DFFFE0,stroke:#28A745,color:#22863A
    classDef database fill:#FFF5B1,stroke:#DBAB09,color:#735C0F
    classDef external fill:#F5E1FF,stroke:#8250DF,color:#5729CE
    classDef tooling fill:#F0F0F0,stroke:#6A737D,color:#24292E
```
