# trstlabs/intento architecture

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

- Interactive diagram: https://gitdiagram.com/trstlabs/intento
- Repository: https://github.com/trstlabs/intento

## Overview

##### Project Type & Purpose
- Full-stack blockchain application (Cosmos SDK).
- Purpose: Process “intent-based” actions (flows) on-chain and across IBC-connected chains via a custom module (“intent”).
- Key features: modular Cosmos SDK modules, IBC, gRPC/REST, CLI, Dockerized networks (dockernet), docs.

##### Top-Level Components
a. User Interfaces
– TriggerPortal UI (external frontend, not in repo)
– Command-Line Interface (cmd/intentod & x/*/client/cli)
b. API Layer
– gRPC server (auto-generated from proto/)
– REST server (gRPC-Gateway)
– Swagger/OpenAPI docs (client/docs/swagger-ui)
c. Application Layer
– Cosmos SDK App (app/ & cmd/intentod/main.go)
– Custom modules in x/ (alloc, claim, intent, interchainquery, mint, …)
– Core services: ABCI handlers, message routers, keepers, genesis, upgrades
d. Consensus & Networking
– Tendermint Core (external process, interacts via ABCI)
– IBC stacks (core & applications, in proto/ibc and x/intent’s IBC middleware)
e. Data Store
– KV Store (Cosmos SDK store)
– Proto definitions & codegen (proto/, third_party/proto/)
f. External Chains & Services
– IBC-connected chains (e.g., Gaia, Osmosis, EVM chains via ICS)
– Relayers/Hermes (dockernet/config)
– Block explorer, external oracles, off-chain triggers

##### Relationships & Data Flow
1. User (UI or CLI) → submits Tx via
- REST/gRPC → Cosmos SDK
- CLI (direct to gRPC)
2. Cosmos SDK routes message to appropriate module’s msg_server → Keeper → state changes
3. State changes → ABCI deliver_tx → consensus (Tendermint) → commit
4. Modules may emit IBC packets via IBC module → external chains
5. IBC acknowledgements or callbacks return to appropriate module’s IBC hooks
6. Off-chain components (relayer, TriggerPortal) monitor events and feed conditions back

##### Architectural Patterns & Design Principles
- Layered architecture: UI / API / Application / Consensus / Storage
- Modular Cosmos SDK pattern: each x/<module> contains keeper, msg_server, client, types, genesis, tests
- gRPC-Gateway for REST wrapping of proto definitions
- IBC middleware in x/intent overriding/augmenting core IBC logic
- Code generation (buf, protoc) for proto ↔ Go types ↔ Swagger

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        TriggerPortalUI["TriggerPortal UI"]:::frontend
        CLI["CLI (intentod)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        GRPC["gRPC Server"]:::frontend
        REST["REST Server (gRPC-Gateway)"]:::frontend
        Swagger["Swagger / Swagger-UI"]:::frontend
    end

    %% Proto & Codegen
    subgraph "Proto & Codegen"
        Proto["Proto Definitions & Codegen"]:::storage
    end

    %% Application Layer
    subgraph "Cosmos SDK App Node" 
        App["App Node"]:::app
        subgraph "Custom Modules"
            Alloc["x/alloc Module"]:::module
            Claim["x/claim Module"]:::module
            Intent["x/intent Module"]:::module
            Interchain["x/interchainquery Module"]:::module
            Mint["x/mint Module"]:::module
            CoreSDK["Core SDK Modules (auth, bank, etc.)"]:::module
        end
    end

    %% Consensus & Networking
    subgraph "Consensus & Networking"
        Tendermint["Tendermint Consensus"]:::network
        IBC["IBC Module & Relayer"]:::network
    end

    %% Data Store
    subgraph "Data Store"
        KV["KV Store / State"]:::storage
    end

    %% External Systems
    subgraph "External Systems"
        ExtChains["IBC-Connected Chains"]:::external
        Oracles["External Oracles / Block Explorer"]:::external
    end

    %% Dockerized Network
    subgraph "Dockerized Network"
        Dockernet["Dockernet (docker-compose)"]:::external
    end

    %% Connections
    TriggerPortalUI -->|submit Tx| REST
    TriggerPortalUI -->|submit Tx| GRPC
    CLI -->|submit Tx| GRPC

    REST -->|REST→gRPC| GRPC
    GRPC -->|gRPC Call| App

    App -->|ABCI DeliverTx| Tendermint
    Tendermint -->|Consensus Commit| App

    App -->|Read/Write| KV

    App -->|IBC Packet| IBC
    IBC -->|Packets| ExtChains
    ExtChains -->|Acknowledgements| IBC
    IBC -->|IBC Hooks| App

    Proto -->|Codegen| GRPC
    Proto -->|Codegen| REST
    Proto -->|Codegen| App

    Dockernet -->|deploys| Tendermint
    Dockernet -->|deploys| IBC
    Dockernet -->|deploys| ExtChains
    Dockernet -->|deploys| CLI
    Dockernet -->|deploys| App

    %% Click Events
    click CLI "https://github.com/trstlabs/intento/blob/main/cmd/intentod/main.go"
    click Swagger "https://github.com/trstlabs/intento/blob/main/client/docs/swagger-ui/index.html"
    click GRPC "https://github.com/trstlabs/intento/tree/main/proto/"
    click App "https://github.com/trstlabs/intento/blob/main/app/app.go"
    click Alloc "https://github.com/trstlabs/intento/blob/main/x/alloc/module.go"
    click Claim "https://github.com/trstlabs/intento/blob/main/x/claim/module.go"
    click Intent "https://github.com/trstlabs/intento/blob/main/x/intent/module.go"
    click Interchain "https://github.com/trstlabs/intento/blob/main/x/interchainquery/module.go"
    click Mint "https://github.com/trstlabs/intento/blob/main/x/mint/module.go"
    click IBC "https://github.com/trstlabs/intento/tree/main/third_party/proto/ibc/"
    click Proto "https://github.com/trstlabs/intento/tree/main/proto/"
    click Dockernet "https://github.com/trstlabs/intento/blob/main/dockernet/docker-compose.yml"

    %% Styles
    classDef frontend fill:#DDF,stroke:#333,stroke-width:1px
    classDef app fill:#DFC,stroke:#333,stroke-width:1px
    classDef module fill:#CFC,stroke:#333,stroke-width:1px
    classDef network fill:#FDD,stroke:#333,stroke-width:1px
    classDef storage fill:#CCC,stroke:#333,stroke-width:1px
    classDef external fill:#DFF,stroke:#333,stroke-width:1px
```
