# midnightntwrk/midnight-indexer architecture

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

- Interactive diagram: https://gitdiagram.com/midnightntwrk/midnight-indexer
- Repository: https://github.com/midnightntwrk/midnight-indexer

## Overview

##### Project type and purpose
- This is a Rust-based, domain-driven set of microservices (chain-indexer, indexer-api, wallet-indexer) plus a “standalone” mode that bundles all three into one binary with an in-process SQLite database.
- Purpose: pull block/tx data from a Midnight Node, index it into a database, publish real-time events, and expose a GraphQL API for client apps (e.g. wallets).

1. Midnight Node (external data source)
2. Chain Indexer service
– Fetch module (WebSocket client)
– Domain logic (block, tx, contract actions)
– Storage infra (Postgres or SQLite adapters)
– Pub/Sub publisher (NATS or in-mem)
3. Persistent store
– Postgres cluster (cloud mode) or SQLite file (standalone)
4. Pub/Sub broker
– NATS (cloud) or in-mem pub/sub (standalone)
5. Wallet Indexer service
– Subscribes to transaction events
– Filters & associates wallet addresses
– Persists wallet-specific state
– (Uses same DB, pub/sub infra)
6. Indexer API service
– GraphQL HTTP + WebSocket server
– Queries DB for historical data
– Subscribes to pub/sub for real-time events
7. Clients
– Wallet UI or other end-user applications

- Node → Chain Indexer (WebSocket “fetch blocks/tx”)
- Chain Indexer → Database (write blocks, tx)
- Chain Indexer → Pub/Sub broker (publish new-block, new-tx events)
- Wallet Indexer → Pub/Sub broker (subscribe tx events)
- Wallet Indexer → Database (write wallet-view state)
- Indexer API → Database (graphql queries for blocks/tx)
- Indexer API → Pub/Sub broker (subscribe events for subscriptions)
- Clients ↔ Indexer API (HTTP queries & WebSocket subscriptions)

##### Important architectural patterns & design principles
- Layered “application / domain / infra” structure in each service crate
- Domain-driven design: clear domain models (block, transaction, contract_action)
- Microservices (chain, wallet, API) share common “indexer-common” crate
- Polyglot storage adapters (Postgres vs SQLite) via trait-based infra modules
- Pub/Sub messaging for decoupled real-time notifications (NATS/in-mem)
- Docker & Docker Compose for “cloud” multi-service vs “standalone” unified deployments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    MidnightNode["Midnight Node"]:::external

    %% Cloud Mode
    subgraph "Cloud Mode"
        direction TB
        CI["Chain Indexer"]:::service
        PostgresDB["Postgres DB"]:::db
        NATS["NATS Broker"]:::messaging
        WI["Wallet Indexer"]:::service
        API["Indexer API"]:::service
    end

    %% Standalone Mode
    subgraph "Standalone Mode"
        direction TB
        Standalone["Standalone Bundle"]:::service
        SQLiteDB["SQLite DB"]:::db
        InMem["In-Mem Pub/Sub"]:::messaging
    end

    %% Clients
    Clients["Clients (Wallet UI, Apps)"]:::external

    %% Cloud Mode Flows
    MidnightNode -->|"WebSocket fetch blocks"| CI
    CI -->|"SQL write"| PostgresDB
    CI -->|"publish new-block/tx"| NATS
    NATS -->|"subscribe tx events"| WI
    WI -->|"SQL write wallet state"| PostgresDB
    API -->|"GraphQL queries"| PostgresDB
    API -->|"subscribe events"| NATS
    Clients -->|"HTTP/WS"| API

    %% Standalone Mode Flows
    MidnightNode -->|"WebSocket fetch"| Standalone
    Standalone -->|"SQL write"| SQLiteDB
    Standalone -->|"publish events"| InMem
    InMem -->|"subscribe/process"| Standalone
    Clients -->|"HTTP/WS"| Standalone

    %% Click Events
    click CI "https://github.com/midnightntwrk/midnight-indexer/tree/main/chain-indexer/"
    click WI "https://github.com/midnightntwrk/midnight-indexer/tree/main/wallet-indexer/"
    click API "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-api/"
    click Standalone "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-standalone/"

    click CI "https://github.com/midnightntwrk/midnight-indexer/tree/main/chain-indexer/src/infra/node/"
    click CI "https://github.com/midnightntwrk/midnight-indexer/blob/main/chain-indexer/src/infra/node.rs"
    click CI "https://github.com/midnightntwrk/midnight-indexer/tree/main/chain-indexer/src/domain/"
    click CI "https://github.com/midnightntwrk/midnight-indexer/blob/main/chain-indexer/src/domain.rs"
    click CI "https://github.com/midnightntwrk/midnight-indexer/blob/main/chain-indexer/src/infra/storage/postgres.rs"
    click CI "https://github.com/midnightntwrk/midnight-indexer/blob/main/chain-indexer/src/infra/storage/sqlite.rs"
    click CI "https://github.com/midnightntwrk/midnight-indexer/blob/main/chain-indexer/src/infra.rs"

    click PostgresDB "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-common/migrations/"
    click PostgresDB "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-common/src/infra/sqlx/"

    click NATS "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-common/src/infra/pub_sub/nats/"
    click InMem "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-common/src/infra/pub_sub/in_mem/"

    click WI "https://github.com/midnightntwrk/midnight-indexer/blob/main/wallet-indexer/src/application.rs"
    click WI "https://github.com/midnightntwrk/midnight-indexer/blob/main/wallet-indexer/src/infra.rs"
    click WI "https://github.com/midnightntwrk/midnight-indexer/tree/main/wallet-indexer/src/domain/"
    click WI "https://github.com/midnightntwrk/midnight-indexer/blob/main/wallet-indexer/src/domain.rs"
    click WI "https://github.com/midnightntwrk/midnight-indexer/blob/main/wallet-indexer/src/infra/storage/postgres.rs"
    click WI "https://github.com/midnightntwrk/midnight-indexer/blob/main/wallet-indexer/src/infra/storage/sqlite.rs"

    click API "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-api/src/infra/api/v1/"
    click API "https://github.com/midnightntwrk/midnight-indexer/blob/main/indexer-api/src/infra/api.rs"
    click API "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-api/src/domain/"
    click API "https://github.com/midnightntwrk/midnight-indexer/blob/main/indexer-api/src/domain.rs"
    click API "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-api/src/infra/storage/postgres/"
    click API "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-api/src/infra/storage/sqlite/"

    click Standalone "https://github.com/midnightntwrk/midnight-indexer/tree/main/indexer-common/src/"

    %% Styles
    classDef service fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef db fill:#d4edda,stroke:#333,stroke-width:1px
    classDef messaging fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-dasharray: 5 5
```
