# gonka-ai/gonka architecture

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

- Interactive diagram: https://gitdiagram.com/gonka-ai/gonka
- Repository: https://github.com/gonka-ai/gonka

## Overview

##### Project type and purpose
- Gonka is a decentralized, containerized AI infrastructure made of three primary node types:
- Chain node (inference-chain) – a Cosmos-SDK blockchain that handles consensus, state management, on-chain governance and task receipts.
- API node (decentralized-api) – a Go microservice that bridges user/developer requests, off-chain orchestration, validation scheduling, and submits transactions to the chain.
- ML node (mlnode) – a Python/Docker service running AI workloads (training, inference, Proof-of-Work 2.0), exposing gRPC/REST endpoints to the API node.
- Supporting artifacts: cosmovisor for chain upgrades, client-libs for scripting, Testermint for integration tests, Kubernetes manifests and Docker Compose for deployments.

##### File structure
- Top-level directories show clear service separation:
- /inference-chain – blockchain application written in Go (Cosmos SDK modules under x/…/, cmd/inferenced, app).
- /decentralized-api – coordination layer in Go, with packages for event listeners, broker, cosmosclient, gRPC/REST handlers, SQLite config store.
- /mlnode – Python packages for inference, training, GPU management, POW, service management, plus Dockerfiles and integration/unit tests.
- Deployment artifacts:
- /local-test-net, /test-net-cloud – Docker Compose and K8s configs.
- /proxy, /proxy-ssl, /tmkms – reverse proxy, SSL automation, key management.
- CI/CD:
- .github workflows for build, test, deploy.
- Integration tests:
- /testermint – Kotlin-based end-to-end tests emulating ml nodes with WireMock.

##### README insights
- Modular microservices communicating via REST/gRPC and event-driven patterns.
- Emphasis on containerization, independent scaling, and composable deployments.
- Core orchestration flows: developers use a CLI → API node → ML node execution → API schedules validation → submits proofs to chain.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Clients"
        CLI["CLI / Browser / Scripts"]:::external
    end

    subgraph "API Layer"
        Server["API Node (Go)"]:::service
        EventListener["Event Listener"]:::service
        Broker["Task Broker & Scheduler"]:::service
        CosmosClient["Cosmos Client"]:::service
        ConfigStore["SQLite Config Store"]:::storage
        NATSQueue["Event Bus / NATS Queue"]:::queue
        CompletionAPI["Completion API Adapter"]:::service
    end

    subgraph "ML Layer"
        Inference["Inference Service"]:::service
        POW["Proof-of-Work Service"]:::service
        Training["Training Service"]:::service
        Common["Common Utilities"]:::service
    end

    subgraph "Chain Layer"
        subgraph "Chain Node (Cosmos-SDK)"
            App["App Module"]:::service
            XModules["x/ Modules"]:::service
            Proto["Proto Definitions"]:::service
            CosmovisorChain["Cosmovisor"]:::service
            Cmd["CLI & Daemon"]:::service
        end
    end

    subgraph "External Services"
        OpenAI["OpenAI Completion API"]:::external
        DockerReg["Docker Registry"]:::external
        GCP["GCP / Cloud Services"]:::external
    end

    subgraph "Deployment & CI/CD"
        DockerCompose["Local Docker Compose"]:::infra
        K8s["Kubernetes Manifests"]:::infra
        ClientLibs["Client Libraries"]:::infra
        Testermint["Integration Tests"]:::infra
        TMKMS["TMKMS Service"]:::infra
        GitHubCI["GitHub Workflows"]:::infra
    end

    CLI -->|"HTTP/gRPC"| Server
    Server -->|"write config"| ConfigStore
    Server -->|"schedule task"| Broker
    Broker -.->|"enqueue"| NATSQueue
    NATSQueue -.->|"task"| Inference
    NATSQueue -.->|"task"| POW
    NATSQueue -.->|"task"| Training
    Inference -->|"results"| Server
    POW -->|"pow results"| Server
    Training -->|"training results"| Server
    Server -->|"validate subset"| CosmosClient
    CosmosClient -->|"submit tx"| Cmd
    Cmd -->|"process tx"| App
    App -->|"calls keeper"| XModules
    XModules -->|"use protobuf"| Proto
    CosmovisorChain -.->|"upgrade management"| Cmd
    XModules -->|"emit events"| EventListener
    EventListener -->|"deliver events"| Server
    Server -->|"fetch completion"| CompletionAPI
    CompletionAPI -->|"calls"| OpenAI

    DockerCompose --- Server
    DockerCompose --- Cmd
    DockerCompose --- Inference
    K8s --- Server
    K8s --- Cmd
    K8s --- Inference
    GitHubCI --- DockerCompose
    GitHubCI --- K8s
    ClientLibs --- CLI
    Testermint --- Server
    Testermint --- Cmd
    TMKMS --- Cmd
    DockerReg --- DockerCompose
    DockerReg --- K8s

    click Server "https://github.com/gonka-ai/gonka/blob/main/decentralized-api/main.go"
    click EventListener "https://github.com/gonka-ai/gonka/tree/main/decentralized-api/internal/event_listener/"
    click Broker "https://github.com/gonka-ai/gonka/tree/main/decentralized-api/broker/"
    click CosmosClient "https://github.com/gonka-ai/gonka/tree/main/decentralized-api/cosmosclient/"
    click ConfigStore "https://github.com/gonka-ai/gonka/blob/main/decentralized-api/apiconfig/sqlite_store.go"
    click NATSQueue "https://github.com/gonka-ai/gonka/tree/main/decentralized-api/internal/nats/"
    click CompletionAPI "https://github.com/gonka-ai/gonka/tree/main/decentralized-api/completionapi/"
    click Inference "https://github.com/gonka-ai/gonka/tree/main/mlnode/packages/api/src/api/"
    click POW "https://github.com/gonka-ai/gonka/tree/main/mlnode/packages/pow/"
    click Training "https://github.com/gonka-ai/gonka/tree/main/mlnode/packages/train/"
    click Common "https://github.com/gonka-ai/gonka/tree/main/mlnode/packages/common/"
    click ClientLibs "https://github.com/gonka-ai/gonka/tree/main/client-libs/"
    click Testermint "https://github.com/gonka-ai/gonka/tree/main/testermint/"
    click TMKMS "https://github.com/gonka-ai/gonka/tree/main/tmkms/"
    click DockerCompose "https://github.com/gonka-ai/gonka/tree/main/local-test-net/"
    click K8s "https://github.com/gonka-ai/gonka/tree/main/test-net-cloud/k8s/"
    click DockerReg "https://github.com/gonka-ai/gonka/tree/main/proxy/"
    click GCP "https://github.com/gonka-ai/gonka/tree/main/deploy/test/"
    click GitHubCI "https://github.com/gonka-ai/gonka/tree/main/.github/workflows/"
    click App "https://github.com/gonka-ai/gonka/tree/main/inference-chain/app/"
    click XModules "https://github.com/gonka-ai/gonka/tree/main/inference-chain/x/"
    click Proto "https://github.com/gonka-ai/gonka/tree/main/inference-chain/proto/"
    click CosmovisorChain "https://github.com/gonka-ai/gonka/tree/main/inference-chain/cosmovisor/"
    click Cmd "https://github.com/gonka-ai/gonka/tree/main/inference-chain/cmd/inferenced/"

    classDef service fill:#cce5ff,stroke:#3399ff;
    classDef storage fill:#ccffcc,stroke:#339933;
    classDef queue fill:#ffe6cc,stroke:#ff6600;
    classDef external fill:#f2f2f2,stroke:#888888,stroke-dasharray: 5 5;
    classDef infra fill:#f9f9f9,stroke:#666666;
```
