# ggezlabs/ggezchain architecture

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

- Interactive diagram: https://gitdiagram.com/ggezlabs/ggezchain
- Repository: https://github.com/ggezlabs/ggezchain

## Overview

##### Project Type & Purpose
- This is a full-stack blockchain application built with the Cosmos SDK (Go) and Tendermint, aiming to tokenize real-world assets for ReFi.
- Core features include on-chain modules (ACL, Trade, IBC, bank, gov, staking, wasm), a custom application binary (`ggezchaind`), Protobuf/gRPC APIs, CLI, tests, docs, and CI/CD.

##### Main Components
a. **Node & Application Layer**
- Tendermint Consensus Engine (ABCI server)
- Cosmos SDK-based application (`app/app.go`, `app/ante.go`, modules under `x/…`)
- Modules: ACL, Trade, IBC, WASM, plus standard Cosmos modules (bank, distribution, gov, staking, slashing, evidence, vesting)
- State Store: BoltDB/LevelDB KV stores managed by each module
b. **API Layer**
- gRPC services auto-generated from `proto/` definitions (query, tx)
- gRPC Gateway / REST endpoints (OpenAPI spec under `docs/static/openapi.yml`)
- CLI (`cmd/ggezchaind`) invoking gRPC/RPC methods
c. **Protobuf Definitions & Codegen**
- `proto/` directory with `.proto` files for each module
- Codegen config via Buf (`buf.yaml`, `buf.gen.*.yaml`) producing Go, Pulsar, Swagger, TypeScript clients
- `api/ggezchain` contains Pulsar-generated code
d. **Client Tools & Scripts**
- Dockerfile & Makefile for build/release (`.github/workflows/release.yml`, `goreleaser.yaml`)
- Helper scripts (`scripts/`) for linting, mock generation
e. **Testing**
- Unit/integration tests in `x/…/keeper`, `tests/integrations`, `tests/e2e`
- Simulation tests in `app/sim_…` and module simulation code under `x/…/simulation`

##### Relationships & Data Flow
- **Consensus <→ Application**: Tendermint delivers transactions via ABCI to the app.
- **CLI/API → Node**:
- CLI invokes gRPC/RPC endpoints on `ggezchaind`.
- REST calls via gRPC-Gateway translate to gRPC methods.
- **Module Interactions**:
- AnteHandler (fee checks, auth) → each module’s handler → state updates
- IBC module handles cross-chain packets → other modules may respond
- **State Persistence**: Each module has its own KV store namespace, all stored in a single underlying DB.
- **Protobuf Codegen**: .proto → generated Go/Pulsar/TS code → used by CLI, API, modules.

##### Architectural Patterns & Design Principles
- **Modular Architecture**: Each feature isolated in its own Cosmos SDK module under `x/…`, promoting separation of concerns, pluggability, and testability.
- **Layered Design**:
- Network/Consensus (Tendermint)
- Application (ABCI + SDK modules)
- API/CLI (gRPC, REST, Pulsar pub/sub)
- **Codegen-Driven**: Centralized Protobuf definitions ensure consistency across client/server and reduce manual wiring.
- **Plugin Pattern**: Modules register message handlers, query services, simulation hooks at app initialization (`app/module.go`, `x/…/module.go`).
- **CI/CD Pipeline**: Automated release (GitHub Actions + GoReleaser), linting, mockgen in scripts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% On-Chain Components
    subgraph "On-Chain Components"
        subgraph "Consensus Layer"
            TM["Tendermint Core<br/>(ABCI Server)"]:::core
        end
        subgraph "Application Core"
            App["ggezchaind (ABCI + Modules)"]:::core
            Ante["AnteHandler"]:::module
            subgraph "Modules"
                ACL["ACL Module"]:::module
                TRADE["Trade Module"]:::module
                IBC["IBC Module"]:::module
                WASM["WASM Module"]:::module
                STD["Standard Cosmos SDK Modules"]:::module
            end
        end
        DB["KV Store<br/>(LevelDB/BoltDB)"]:::infra
    end

    %% API & CLI
    subgraph "API & CLI"
        CLI["CLI (ggezchaind commands)"]:::api
        GRPC["gRPC Server"]:::api
        REST["REST Gateway<br/>(OpenAPI)"]:::api
        GENAPI["Generated API Code"]:::api
    end

    %% External
    subgraph "External"
        RELAYER["Relayer / External Chains"]:::external
    end

    %% Codegen Pipeline
    subgraph "Codegen Pipeline"
        PROTO["Protobuf Definitions"]:::infra
        BUF["Buf Config"]:::infra
        GEN["Generated Clients<br/>(Go, Pulsar, TS)"]:::infra
    end

    %% CI/CD & Build
    subgraph "CI/CD & Build"
        DOCKER["Dockerfile & Makefile"]:::infra
        CI["GitHub Actions<br/>& GoReleaser"]:::infra
        SCRIPTS["Helper Scripts"]:::infra
    end

    %% Testing
    subgraph "Testing"
        UT["Unit Tests"]:::infra
        INT["Integration Tests"]:::infra
        E2E["E2E Tests"]:::infra
        SIM["Simulation Tests"]:::infra
    end

    %% Connections
    CLI -->|"calls gRPC"| GRPC
    REST -->|"REST→gRPC"| GRPC
    GRPC -->|"ABCI Requests"| App
    TM <-->|"ABCI"| App
    App -->|"fee/auth"| Ante
    Ante -->|"dispatch to modules"| ACL
    Ante --> TRADE
    Ante --> IBC
    Ante --> WASM
    Ante --> STD
    ACL -->|"state update"| DB
    TRADE --> DB
    IBC --> DB
    WASM --> DB
    STD --> DB
    IBC -->|"IBC packets"| RELAYER

    PROTO --> BUF
    BUF --> GEN
    GEN --> GENAPI

    CLI --> GENAPI
    GRPC --> GENAPI

    DOCKER --> CI
    SCRIPTS --> CI

    UT --> ACL
    UT --> TRADE
    INT --> CLI
    INT --> ACL
    INT --> TRADE
    E2E --> CLI
    E2E --> GRPC
    E2E --> App
    SIM --> App
    SIM --> ACL
    SIM --> TRADE

    %% Click Events
    click TM "https://github.com/ggezlabs/ggezchain/blob/main/cmd/ggezchaind/main.go"
    click TM "https://github.com/ggezlabs/ggezchain/blob/main/app/app.go"
    click App "https://github.com/ggezlabs/ggezchain/blob/main/app/app.go"
    click Ante "https://github.com/ggezlabs/ggezchain/blob/main/app/ante.go"
    click IBC "https://github.com/ggezlabs/ggezchain/blob/main/app/ibc.go"
    click WASM "https://github.com/ggezlabs/ggezchain/blob/main/app/wasm.go"
    click ACL "https://github.com/ggezlabs/ggezchain/tree/main/x/acl"
    click TRADE "https://github.com/ggezlabs/ggezchain/tree/main/x/trade"
    click GRPC "https://github.com/ggezlabs/ggezchain/tree/main/api/ggezchain"
    click REST "https://github.com/ggezlabs/ggezchain/blob/main/docs/static/openapi.yml"
    click CLI "https://github.com/ggezlabs/ggezchain/blob/main/cmd/ggezchaind/main.go"
    click PROTO "https://github.com/ggezlabs/ggezchain/tree/main/proto/ggezchain"
    click BUF "https://github.com/ggezlabs/ggezchain/blob/main/proto/buf.yaml"
    click GEN "https://github.com/ggezlabs/ggezchain/tree/main/api/ggezchain"
    click DOCKER "https://github.com/ggezlabs/ggezchain/tree/main/Dockerfile"
    click CI "https://github.com/ggezlabs/ggezchain/blob/main/.github/workflows/release.yml"
    click SCRIPTS "https://github.com/ggezlabs/ggezchain/blob/main/scripts/makefiles/lint.mk"
    click INT "https://github.com/ggezlabs/ggezchain/tree/main/tests/integrations"
    click E2E "https://github.com/ggezlabs/ggezchain/tree/main/tests/e2e"
    click SIM "https://github.com/ggezlabs/ggezchain/blob/main/app/sim_bench_test.go"

    %% Styles
    classDef core fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef module fill:#DFFFD6,stroke:#333,stroke-width:1px
    classDef api fill:#FFD8B1,stroke:#333,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px
```
