# bryanlabs/cosmos-indexer-sdk architecture

> Architecture diagram of the GitHub repository bryanlabs/cosmos-indexer-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bryanlabs/cosmos-indexer-sdk
- Repository: https://github.com/bryanlabs/cosmos-indexer-sdk

## Overview

##### Project Type and Purpose
- This project is an open-source indexing tool built in Go that processes and indexes data from Cosmos SDK-based blockchains. Its purpose is to provide a generalized Transaction/Event database schema for Cosmos chains, making it easier for developers to store and query custom indexed data.
- The README emphasizes CLI interaction, configuration via files, and a quick-start demo using docker-compose to run the indexer along with a database and web client. This indicates both a backend service and support for external integrations.

##### Analyzing the File Structure
- Top-level directories indicate separation of responsibilities:
- “cmd”: Contains the main entry point for the CLI application (index.go, root.go).
- “config”: Houses configuration files and examples (e.g., config.toml.example) that define logging, database, base settings, and probe settings.
- “core”: Implements the core business logic like processing blocks, events, and transactions.
- “cosmos”: Contains modules that handle Cosmos-specific events, normalization, and specialized modules (e.g., parsing transaction logic in cosmos/modules/tx).
- “db”: Manages database connections and data models (with models for blocks, transactions, addresses, etc.).
- “filter”: Implements filters for block events and messages.
- “indexer” and “parsers”: Provide additional processing and customization for indexing workflows.
- “rpc”: Handles remote procedure call interactions, probably with the Cosmos chain for fetching data.
- “probe”: Likely assists with probing chain data—the README explicitly mentions an integrated probe.
- Supporting directories like “docs”, “examples”, “setup”, and “tools” provide usage documentation, sample configurations and scripts to aid deployment.
- The presence of docker files, docker-compose.yaml, and Makefile indicates that containerized deployment and automated builds/test routines are integral to the project.

##### Final Advice
- Essential components based on the directory layout and README details. Do not omit custom modules (like “cosmos/modules”) that illustrate how the indexer adapts to different Cosmos SDK chains.
- That the dependency flow and configuration injection points are clear. This not only helps in understanding the runtime behavior but also aids in subsequent debugging or enhancements.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration & Setup
    subgraph "Configuration & Setup"
        A["Configuration & Setup"]
    end

    %% Interface Layer
    subgraph "Interface Layer"
        B["CLI & Command Processor"]
    end

    %% Ingestion Layer
    subgraph "Ingestion Layer"
        C["Blockchain RPC"]
        D["Integrated Probe"]
    end

    %% Processing Layer
    subgraph "Processing Layer"
        E["Core Event Processing"]
        F["Cosmos Normalization Module"]
        G["Filtering Engine"]
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        H["Database Access Layer"]
    end

    %% Auxiliary Tools
    subgraph "Auxiliary"
        I["Auxiliary Tools"]
    end

    %% Connections - Data Flow
    A --> B
    B --> E
    C --> E
    D --> E
    E --> F
    F --> E
    E --> G
    G --> H

    %% Configuration injection to multiple components (dashed lines)
    A --- H
    A --- I

    %% Auxiliary tool reporting diagnostics to DB
    I -->|"report"| H

    %% Click Events for Configuration & Setup
    click A "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/config/"
    click A "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/setup/"

    %% Click Events for CLI / Command Interface
    click B "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/cmd/index.go"
    click B "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/cmd/root.go"

    %% Click Events for Core Processing Module
    click E "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/core/processor.go"
    click E "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/indexer/process.go"

    %% Click Events for Cosmos-Specific Modules
    click F "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/cosmos/"
    click F "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/cosmos/modules/tx/logic.go"

    %% Click Events for Filtering Mechanism
    click G "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/filter/"
    click G "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/filter/block_event_filter_registry.go"

    %% Click Events for RPC Component
    click C "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/rpc/"
    click C "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/rpc/blocks.go"
    click C "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/rpc/requests.go"

    %% Click Events for Probe Component
    click D "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/probe/"
    click D "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/probe/probe.go"

    %% Click Events for Database Layer
    click H "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/db/"

    %% Click Events for Auxiliary Tools
    click I "https://github.com/bryanlabs/cosmos-indexer-sdk/tree/main/tools/"
    click I "https://github.com/bryanlabs/cosmos-indexer-sdk/blob/main/tools/dump-failed-block-heights/main.py"

    %% Styles
    classDef config fill:#A2D9CE,stroke:#1ABC9C,stroke-width:2px;
    classDef cli fill:#F8C471,stroke:#F39C12,stroke-width:2px;
    classDef rpc fill:#85C1E9,stroke:#3498DB,stroke-width:2px;
    classDef probe fill:#F1948A,stroke:#E74C3C,stroke-width:2px;
    classDef processor fill:#BB8FCE,stroke:#8E44AD,stroke-width:2px;
    classDef cosmos fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef filter fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef db fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef auxiliary fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px;

    class A config;
    class B cli;
    class C rpc;
    class D probe;
    class E processor;
    class F cosmos;
    class G filter;
    class H db;
    class I auxiliary;
```
