# pokt-network/poktroll architecture

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

- Interactive diagram: https://gitdiagram.com/pokt-network/poktroll
- Repository: https://github.com/pokt-network/poktroll

## Overview

##### Project type and purpose
- This is a full-stack blockchain node implementation (Pocket Network Shannon upgrade) built on the Cosmos SDK (CometBFT) in Go. It comprises:
- A core application (“pocketd”) exposing an ABCI app and gRPC/REST APIs
- A collection of Cosmos-SDK modules (x/application, x/gateway, x/session, x/service, x/supplier, x/proof, x/migration, x/tokenomics, x/shared)
- Client libraries (pkg/client) for external consumers
- CLI tooling (cmd/pocketd, cmd/flags, cmd/logger, cmd/morse_keys)
- Testing & dev-ops (e2e, load-testing, localnet Kubernetes manifests, Tiltfile, Makefiles)
- Documentation (docusaurus)

##### File structure
- Top-level “cmd” contains the node binary and CLIs
- “app” holds the ABCI wiring: app.go, keepers, genesis, upgrades
- “x/…” subdirectories each implement one Cosmos SDK module
- “api” contains auto-generated GRPC handlers for module RPCs
- “pkg” provides reusable components: client SDK, cryptography, relayer, caching, telemetry, retry logic
- “proto” houses all .proto definitions and codegen config
- “e2e” and “load-testing” drive BDD and stress tests
- “localnet” contains Kubernetes charts & Grafana dashboards for local cluster
- “tools” and “scripts” deliver helpers (migration scripts, docs-generation, load-test manifests)

##### Additional insights from README
- It confirms use of Go v1.23, gRPC (Protobuf), and the Shannon network upgrade
- Documentation is externalized to Docusaurus, deployed at dev.poktroll.com

##### Elements
- Block flow (CometBFT → ABCI → Modules → DB)
- API calls (SDK/CLI → gRPC/REST → Modules)
- Event streaming (Modules → Pulsar → Relayer/Telemetry)
- Blue for infra (Consensus, DB, Pulsar, Kubernetes)
- Green for application modules
- Orange for API/SDK/CLI
- Gray for testing/devops

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consensus Engine Layer
    subgraph "Consensus Engine Layer"
        CB["CometBFT (Tendermint Core)"]:::infra
    end

    %% ABCI Application Layer
    subgraph "ABCI Application Layer"
        ABCI["ABCI App"]:::infra
        Ante["Ante Handler"]:::infra
        Export["Export & Genesis Logic"]:::infra
        Upgrades["Upgrades Logic (Shannon)"]:::infra
        subgraph "Cosmos-SDK Modules"
            AppMod["x/application"]:::app
            GateMod["x/gateway"]:::app
            SessMod["x/session"]:::app
            ServMod["x/service"]:::app
            SuppMod["x/supplier"]:::app
            ProofMod["x/proof"]:::app
            MigMod["x/migration"]:::app
            TokenMod["x/tokenomics"]:::app
            SharedMod["x/shared"]:::app
        end
    end

    %% State Storage
    DB["Multi-store DB"]:::infra

    %% Event Bus
    subgraph "Event Bus"
        Pulsar["Apache Pulsar Cluster"]:::infra
    end

    %% API Layer
    subgraph "API Layer"
        GRPC["gRPC Servers"]:::api
        REST["gRPC-Gateway / REST"]:::api
    end

    %% Clients & CLI
    subgraph "Clients"
        CLI["CLI (pocketd)"]:::client
        SDK["Client SDK"]:::client
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        Relayer["Relayer"]:::client
        Telemetry["Telemetry & Metrics"]:::client
    end

    %% Testing & DevOps
    subgraph "Testing & DevOps"
        E2E["E2E Tests"]:::devops
        Load["Load Testing"]:::devops
        Localnet["Localnet K8s"]:::devops
        Doc["Documentation Portal"]:::devops
    end

    %% Flows and relationships
    CB <--> ABCI
    ABCI -->|read/write state| DB
    ABCI --> Ante
    ABCI --> Export
    ABCI --> Upgrades
    ABCI --> AppMod
    ABCI --> GateMod
    ABCI --> SessMod
    ABCI --> ServMod
    ABCI --> SuppMod
    ABCI --> ProofMod
    ABCI --> MigMod
    ABCI --> TokenMod
    ABCI --> SharedMod

    AppMod -->|publish/subscribe events| Pulsar
    GateMod -->|publish/subscribe events| Pulsar
    SessMod -->|publish/subscribe events| Pulsar
    ServMod -->|publish/subscribe events| Pulsar
    SuppMod -->|publish/subscribe events| Pulsar
    ProofMod -->|publish/subscribe events| Pulsar
    MigMod -->|publish/subscribe events| Pulsar
    TokenMod -->|publish/subscribe events| Pulsar
    SharedMod -->|publish/subscribe events| Pulsar

    Pulsar --> Relayer
    Pulsar --> Telemetry

    CLI --> GRPC
    CLI --> REST
    SDK --> GRPC
    SDK --> REST

    GRPC <--> AppMod
    GRPC <--> GateMod
    GRPC <--> SessMod
    GRPC <--> ServMod
    GRPC <--> SuppMod
    GRPC <--> ProofMod
    GRPC <--> MigMod
    GRPC <--> TokenMod
    GRPC <--> SharedMod

    E2E --> ABCI
    Load --> ABCI
    Localnet --> CB
    Localnet --> Pulsar
    Localnet --> Telemetry
    Localnet --> Doc

    %% Click Events
    click ABCI "https://github.com/pokt-network/poktroll/blob/main/app/app.go"
    click Ante "https://github.com/pokt-network/poktroll/blob/main/app/ante.go"
    click Export "https://github.com/pokt-network/poktroll/blob/main/app/export.go"
    click Export "https://github.com/pokt-network/poktroll/blob/main/app/genesis.go"
    click Upgrades "https://github.com/pokt-network/poktroll/blob/main/app/upgrades/v0.1.11.go"
    click AppMod "https://github.com/pokt-network/poktroll/tree/main/x/application"
    click GateMod "https://github.com/pokt-network/poktroll/tree/main/x/gateway"
    click SessMod "https://github.com/pokt-network/poktroll/tree/main/x/session"
    click ServMod "https://github.com/pokt-network/poktroll/tree/main/x/service"
    click SuppMod "https://github.com/pokt-network/poktroll/tree/main/x/supplier"
    click ProofMod "https://github.com/pokt-network/poktroll/tree/main/x/proof"
    click MigMod "https://github.com/pokt-network/poktroll/tree/main/x/migration"
    click TokenMod "https://github.com/pokt-network/poktroll/tree/main/x/tokenomics"
    click SharedMod "https://github.com/pokt-network/poktroll/tree/main/x/shared"
    click GRPC "https://github.com/pokt-network/poktroll/tree/main/api/pocket"
    click CLI "https://github.com/pokt-network/poktroll/blob/main/cmd/pocketd/main.go"
    click SDK "https://github.com/pokt-network/poktroll/tree/main/pkg/client"
    click Relayer "https://github.com/pokt-network/poktroll/tree/main/pkg/relayer"
    click Telemetry "https://github.com/pokt-network/poktroll/blob/main/telemetry/telemetry.go"
    click E2E "https://github.com/pokt-network/poktroll/tree/main/e2e/tests"
    click Load "https://github.com/pokt-network/poktroll/tree/main/load-testing/"
    click Localnet "https://github.com/pokt-network/poktroll/tree/main/localnet/kubernetes"
    click Doc "https://github.com/pokt-network/poktroll/tree/main/docusaurus/"

    %% Styles
    classDef infra fill:#AED6F1,stroke:#000;
    classDef app fill:#ABEBC6,stroke:#000;
    classDef api fill:#F9E79F,stroke:#000;
    classDef client fill:#F5B7B1,stroke:#000;
    classDef devops fill:#D7BDE2,stroke:#000;
```
