# hcftrize/explorize architecture

> Architecture diagram of the GitHub repository hcftrize/explorize, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hcftrize/explorize
- Repository: https://github.com/hcftrize/explorize

## Overview

Explorize is a Python indexer that copies RIZE Transfer events from four EVM chains into Postgres, then enriches venue-related transactions into trades and liquidity records. Operators invoke its CLI for backfill/sync, diagnostics, market enrichment, pool discovery and CCIP reconciliation; the documented website/API consumes the database from another repository. The graph includes the documented holder/governance and diagnostic capabilities, plus RPC, registry and database layers. Some subsystem internals are unsampled, so their connections are shown only where the README or indexed/read source supports them.

Main entry points: [`indexer/__main__.py`](https://github.com/hcftrize/explorize/blob/main/indexer/__main__.py) (Indexer CLI), [`indexer/enrich.py`](https://github.com/hcftrize/explorize/blob/main/indexer/enrich.py) (Market enrichment), [`indexer/sync.py`](https://github.com/hcftrize/explorize/blob/main/indexer/sync.py) (Transfer sync), [`indexer/db.py`](https://github.com/hcftrize/explorize/blob/main/indexer/db.py) (Postgres access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Transfer indexing"]
  node_sync["Transfer sync<br/>[sync.py]"]
  node_logs["Log decoding<br/>[logs.py]"]
end

subgraph group_market["Market enrichment"]
  node_registry["Venue registry<br/>[registry.py]"]
  node_receipts["Receipt reconciliation<br/>[receipts.py]"]
  node_venues["Venue adapters<br/>[venues.py]"]
  node_enrich["Market enrichment<br/>[enrich.py]"]
  node_ccip["Bridge reconciliation<br/>[ccip.py]"]
  node_holders["Holder indexing<br/>[holders.py]"]
end

subgraph group_chain_data["Chain data"]
  node_config["Chain configuration<br/>[config.py]"]
  node_rpc["JSON-RPC client<br/>[rpc.py]"]
  node_multicall["Multicall reader<br/>[multicall.py]"]
end

subgraph group_operations["Operations"]
  node_cli["Indexer CLI<br/>[__main__.py]"]
  node_marketcheck["Market diagnostics<br/>[market_check.py]"]
  node_governance["Governance checks<br/>[governance.py]"]
  node_checks["Probe and verify<br/>[checks.py]"]
end

subgraph group_storage["Persistence and consumers"]
  node_db["Postgres access<br/>[db.py]"]
  node_postgres[("Postgres database<br/>[schema.sql]")]
end

node_operator(("Operator"))
node_chains{{"EVM chains"}}
node_website["API and explorer page"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"runs sync"| node_sync
node_sync -->|"loads chains"| node_config
node_sync -->|"fetches logs"| node_rpc
node_sync -->|"decodes ranges"| node_logs
node_sync -->|"saves ranges"| node_db
node_rpc -->|"queries"| node_chains
node_db -->|"reads and writes"| node_postgres
node_cli -->|"runs enrichment"| node_enrich
node_enrich -->|"reconciles transactions"| node_receipts
node_enrich -->|"adapts venue events"| node_venues
node_enrich -->|"uses venue metadata"| node_registry
node_enrich -->|"stores market records"| node_db
node_venues -->|"looks up pools"| node_registry
node_cli -->|"runs reconciliation"| node_ccip
node_cli -.->|"runs holder job"| node_holders
node_holders -->|"reads balances"| node_multicall
node_holders -->|"persists holder data"| node_db
node_cli -->|"runs diagnostics"| node_governance
node_governance -->|"batches contract reads"| node_multicall
node_cli -->|"runs checks"| node_checks
node_checks -->|"probes chain state"| node_rpc
node_checks -->|"checks stored data"| node_db
node_cli -->|"runs market diagnostics"| node_marketcheck
node_marketcheck -->|"reconciles receipts"| node_receipts
node_marketcheck -->|"previews records"| node_enrich
node_marketcheck -->|"decodes venue events"| node_venues
node_website -->|"reads indexed data"| node_postgres

click node_cli "https://github.com/hcftrize/explorize/blob/main/indexer/__main__.py"
click node_config "https://github.com/hcftrize/explorize/blob/main/indexer/config.py"
click node_rpc "https://github.com/hcftrize/explorize/blob/main/indexer/rpc.py"
click node_sync "https://github.com/hcftrize/explorize/blob/main/indexer/sync.py"
click node_logs "https://github.com/hcftrize/explorize/blob/main/indexer/logs.py"
click node_db "https://github.com/hcftrize/explorize/blob/main/indexer/db.py"
click node_postgres "https://github.com/hcftrize/explorize/blob/main/db/schema.sql"
click node_registry "https://github.com/hcftrize/explorize/blob/main/indexer/registry.py"
click node_receipts "https://github.com/hcftrize/explorize/blob/main/indexer/receipts.py"
click node_venues "https://github.com/hcftrize/explorize/blob/main/indexer/venues.py"
click node_enrich "https://github.com/hcftrize/explorize/blob/main/indexer/enrich.py"
click node_marketcheck "https://github.com/hcftrize/explorize/blob/main/indexer/market_check.py"
click node_ccip "https://github.com/hcftrize/explorize/blob/main/indexer/ccip.py"
click node_holders "https://github.com/hcftrize/explorize/blob/main/indexer/holders.py"
click node_governance "https://github.com/hcftrize/explorize/blob/main/indexer/governance.py"
click node_checks "https://github.com/hcftrize/explorize/blob/main/indexer/checks.py"
click node_multicall "https://github.com/hcftrize/explorize/blob/main/indexer/multicall.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sync,node_logs toneBlue
class node_registry,node_receipts,node_venues,node_enrich,node_ccip,node_holders toneAmber
class node_config,node_rpc,node_multicall,node_website toneMint
class node_cli,node_marketcheck,node_governance,node_checks toneRose
class node_db,node_postgres,node_operator,node_chains toneIndigo
```

## Components

### Transfer indexing

- [Transfer sync](https://github.com/hcftrize/explorize/blob/main/indexer/sync.py): `indexer/sync.py`
- [Log decoding](https://github.com/hcftrize/explorize/blob/main/indexer/logs.py): `indexer/logs.py`

### Market enrichment

- [Venue registry](https://github.com/hcftrize/explorize/blob/main/indexer/registry.py): `indexer/registry.py`
- [Receipt reconciliation](https://github.com/hcftrize/explorize/blob/main/indexer/receipts.py): `indexer/receipts.py`
- [Venue adapters](https://github.com/hcftrize/explorize/blob/main/indexer/venues.py): `indexer/venues.py`
- [Market enrichment](https://github.com/hcftrize/explorize/blob/main/indexer/enrich.py): `indexer/enrich.py`
- [Bridge reconciliation](https://github.com/hcftrize/explorize/blob/main/indexer/ccip.py): `indexer/ccip.py`
- [Holder indexing](https://github.com/hcftrize/explorize/blob/main/indexer/holders.py): `indexer/holders.py`

### Chain data

- [Chain configuration](https://github.com/hcftrize/explorize/blob/main/indexer/config.py): `indexer/config.py`
- [JSON-RPC client](https://github.com/hcftrize/explorize/blob/main/indexer/rpc.py): `indexer/rpc.py`
- [Multicall reader](https://github.com/hcftrize/explorize/blob/main/indexer/multicall.py): `indexer/multicall.py`

### Operations

- [Indexer CLI](https://github.com/hcftrize/explorize/blob/main/indexer/__main__.py): `indexer/__main__.py`
- [Market diagnostics](https://github.com/hcftrize/explorize/blob/main/indexer/market_check.py): `indexer/market_check.py`
- [Governance checks](https://github.com/hcftrize/explorize/blob/main/indexer/governance.py): `indexer/governance.py`
- [Probe and verify](https://github.com/hcftrize/explorize/blob/main/indexer/checks.py): `indexer/checks.py`

### Persistence and consumers

- [Postgres access](https://github.com/hcftrize/explorize/blob/main/indexer/db.py): `indexer/db.py`
- [Postgres database](https://github.com/hcftrize/explorize/blob/main/db/schema.sql): `db/schema.sql`

### Other components

- **Operator**
- **EVM chains**
- **API and explorer page**

## Connections

- Operator → Indexer CLI: runs commands (evidence: `README.md`)
- Indexer CLI → Transfer sync: runs sync (evidence: `README.md`)
- Transfer sync → Chain configuration: loads chains (evidence: `indexer/sync.py`)
- Transfer sync → JSON-RPC client: fetches logs (evidence: `indexer/sync.py`)
- Transfer sync → Log decoding: decodes ranges (evidence: `indexer/sync.py`)
- Transfer sync → Postgres access: saves ranges (evidence: `indexer/sync.py`)
- JSON-RPC client → EVM chains: queries (evidence: `README.md`)
- Postgres access → Postgres database: reads and writes (evidence: `indexer/db.py`)
- Indexer CLI → Market enrichment: runs enrichment (evidence: `README.md`)
- Market enrichment → Receipt reconciliation: reconciles transactions (evidence: `indexer/enrich.py`)
- Market enrichment → Venue adapters: adapts venue events (evidence: `indexer/enrich.py`)
- Market enrichment → Venue registry: uses venue metadata (evidence: `indexer/enrich.py`)
- Market enrichment → Postgres access: stores market records (evidence: `indexer/enrich.py`)
- Venue adapters → Venue registry: looks up pools (evidence: `indexer/venues.py`)
- Indexer CLI → Bridge reconciliation: runs reconciliation (evidence: `README.md`)
- Indexer CLI → Holder indexing: runs holder job
- Holder indexing → Multicall reader: reads balances (evidence: `indexer/holders.py`)
- Holder indexing → Postgres access: persists holder data (evidence: `indexer/holders.py`)
- Indexer CLI → Governance checks: runs diagnostics (evidence: `indexer/__main__.py`)
- Governance checks → Multicall reader: batches contract reads (evidence: `indexer/governance.py`)
- Indexer CLI → Probe and verify: runs checks (evidence: `indexer/__main__.py`)
- Probe and verify → JSON-RPC client: probes chain state (evidence: `indexer/checks.py`)
- Probe and verify → Postgres access: checks stored data (evidence: `indexer/checks.py`)
- Indexer CLI → Market diagnostics: runs market diagnostics (evidence: `indexer/__main__.py`)
- Market diagnostics → Receipt reconciliation: reconciles receipts (evidence: `indexer/market_check.py`)
- Market diagnostics → Market enrichment: previews records (evidence: `indexer/market_check.py`)
- Market diagnostics → Venue adapters: decodes venue events (evidence: `indexer/market_check.py`)
- API and explorer page → Postgres database: reads indexed data (evidence: `README.md`)
