# rumblefishdev/soroban-block-explorer architecture

> Architecture diagram of the GitHub repository rumblefishdev/soroban-block-explorer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rumblefishdev/soroban-block-explorer
- Repository: https://github.com/rumblefishdev/soroban-block-explorer

## Overview

Soroban Block Explorer is a Stellar/Soroban explorer: users search or browse ledger entities in the React SPA, which fetches REST data and presents list, detail, and transaction views. The backend exposes entity APIs over ClickHouse-backed data; ingestion parses ledger data for persistence, while a separate enrichment path fills metadata side tables. The README establishes the product components, and sampled files confirm selected frontend, API, worker, and backfill behavior. Several backend links reflect the tree and README’s architecture; unsampled implementation details are not inferred as specific calls.

Main entry points: [`crates/indexer/src/main.rs`](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/indexer/src/main.rs) (Ledger indexer), [`crates/api/src/main.rs`](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/main.rs) (REST API), [`infra/src/lib/stacks/compute-stack.ts`](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/infra/src/lib/stacks/compute-stack.ts) (AWS runtime), [`web/src/router/routes.ts`](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/router/routes.ts) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Explorer UI"]
  node_spa["Explorer SPA<br/>[app.tsx]"]
  node_router["Routes<br/>[routes.ts]"]
  node_search["Search results"]
  node_pages["Entity pages"]
  node_api_client["API hooks<br/>[client.ts]"]
  node_shared_ui["Shared UI<br/>[index.ts]"]
end

subgraph group_api["API and storage"]
  node_rest["REST API<br/>[main.rs]"]
  node_search_handlers["Search API<br/>[handlers.rs]"]
  node_entity_handlers["Entity APIs<br/>[handlers.rs]"]
  node_entity_queries["Entity queries<br/>[queries.rs]"]
  node_clickhouse[("ClickHouse")]
end

subgraph group_ingest["Ingestion and enrichment"]
  node_indexer["Ledger indexer<br/>[main.rs]"]
  node_backfill["Backfill runner<br/>[main.rs]"]
  node_enrich_publish["Enrichment publisher"]
  node_worker["Enrichment worker<br/>[main.rs]"]
end

subgraph group_shared["Shared data logic"]
  node_parser["XDR parser<br/>[lib.rs]"]
  node_persist["ClickHouse persistence<br/>[persist.rs]"]
  node_enrich_logic["Enrichment logic<br/>[mod.rs]"]
end

node_visitor(("Explorer user"))
node_queue["SQS"]
node_external_metadata["Metadata services"]
node_infra["AWS runtime<br/>[compute-stack.ts]"]

node_visitor -->|"browses"| node_spa
node_spa -->|"matches routes"| node_router
node_router -->|"opens search"| node_search
node_router -->|"opens pages"| node_pages
node_search -->|"queries results"| node_api_client
node_pages -->|"requests data"| node_api_client
node_pages -->|"renders with"| node_shared_ui
node_api_client -->|"HTTP requests"| node_rest
node_rest -->|"dispatches search"| node_search_handlers
node_rest -->|"dispatches entities"| node_entity_handlers
node_entity_handlers -->|"queries"| node_entity_queries
node_entity_queries -->|"reads"| node_clickhouse
node_search_handlers -->|"searches"| node_clickhouse
node_indexer -->|"parses ledgers"| node_parser
node_indexer -->|"persists records"| node_persist
node_persist -->|"writes"| node_clickhouse
node_backfill -->|"backfills through"| node_persist
node_indexer -->|"publishes work"| node_enrich_publish
node_enrich_publish -->|"sends messages"| node_queue
node_queue -->|"delivers records"| node_worker
node_worker -->|"dispatches enrichment"| node_enrich_logic
node_enrich_logic -.->|"fetches metadata"| node_external_metadata
node_enrich_logic -->|"writes side tables"| node_clickhouse
node_infra -->|"hosts"| node_rest
node_infra -->|"hosts"| node_indexer
node_infra -->|"hosts"| node_worker

click node_spa "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/app.tsx"
click node_router "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/router/routes.ts"
click node_search "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/search/useSearchResults.ts"
click node_pages "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/pages/TransactionDetailPage.tsx"
click node_api_client "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/api/client.ts"
click node_shared_ui "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/libs/ui/src/index.ts"
click node_rest "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/main.rs"
click node_search_handlers "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/search/handlers.rs"
click node_entity_handlers "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/transactions/handlers.rs"
click node_entity_queries "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/transactions/queries.rs"
click node_indexer "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/indexer/src/main.rs"
click node_parser "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/xdr-parser/src/lib.rs"
click node_persist "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/db-clickhouse/src/persist.rs"
click node_backfill "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/backfill-runner/src/main.rs"
click node_enrich_publish "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/indexer/src/handler/enrichment_publish.rs"
click node_worker "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/enrichment-worker/src/main.rs"
click node_enrich_logic "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/enrichment-shared/src/enrich_and_persist/mod.rs"
click node_infra "https://github.com/rumblefishdev/soroban-block-explorer/blob/master/infra/src/lib/stacks/compute-stack.ts"

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_spa,node_router,node_search,node_pages,node_api_client,node_shared_ui,node_visitor toneBlue
class node_rest,node_search_handlers,node_entity_handlers,node_entity_queries,node_clickhouse toneAmber
class node_indexer,node_backfill,node_enrich_publish,node_worker toneMint
class node_parser,node_persist,node_enrich_logic toneRose
class node_queue,node_external_metadata toneIndigo
class node_infra toneTeal
```

## Components

### Explorer UI

- [Explorer SPA](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/app.tsx): `web/src/app.tsx`
- [Routes](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/router/routes.ts): `web/src/router/routes.ts`
- [Search results](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/search/useSearchResults.ts): `web/src/search/useSearchResults.ts`
- [Entity pages](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/pages/TransactionDetailPage.tsx): `web/src/pages/TransactionDetailPage.tsx`
- [API hooks](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/web/src/api/client.ts): `web/src/api/client.ts`
- [Shared UI](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/libs/ui/src/index.ts): `libs/ui/src/index.ts`

### API and storage

- [REST API](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/main.rs): `crates/api/src/main.rs`
- [Search API](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/search/handlers.rs): `crates/api/src/search/handlers.rs`
- [Entity APIs](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/transactions/handlers.rs): `crates/api/src/transactions/handlers.rs`
- [Entity queries](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/api/src/transactions/queries.rs): `crates/api/src/transactions/queries.rs`
- **ClickHouse**

### Ingestion and enrichment

- [Ledger indexer](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/indexer/src/main.rs): `crates/indexer/src/main.rs`
- [Backfill runner](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/backfill-runner/src/main.rs): `crates/backfill-runner/src/main.rs`
- [Enrichment publisher](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/indexer/src/handler/enrichment_publish.rs): `crates/indexer/src/handler/enrichment_publish.rs`
- [Enrichment worker](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/enrichment-worker/src/main.rs): `crates/enrichment-worker/src/main.rs`

### Shared data logic

- [XDR parser](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/xdr-parser/src/lib.rs): `crates/xdr-parser/src/lib.rs`
- [ClickHouse persistence](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/db-clickhouse/src/persist.rs): `crates/db-clickhouse/src/persist.rs`
- [Enrichment logic](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/crates/enrichment-shared/src/enrich_and_persist/mod.rs): `crates/enrichment-shared/src/enrich_and_persist/mod.rs`

### Other components

- **Explorer user**
- **SQS**
- **Metadata services**
- [AWS runtime](https://github.com/rumblefishdev/soroban-block-explorer/blob/master/infra/src/lib/stacks/compute-stack.ts): `infra/src/lib/stacks/compute-stack.ts`

## Connections

- Explorer user → Explorer SPA: browses
- Explorer SPA → Routes: matches routes
- Routes → Search results: opens search
- Routes → Entity pages: opens pages
- Search results → API hooks: queries results
- Entity pages → API hooks: requests data
- Entity pages → Shared UI: renders with
- API hooks → REST API: HTTP requests
- REST API → Search API: dispatches search
- REST API → Entity APIs: dispatches entities
- Entity APIs → Entity queries: queries
- Entity queries → ClickHouse: reads
- Search API → ClickHouse: searches
- Ledger indexer → XDR parser: parses ledgers
- Ledger indexer → ClickHouse persistence: persists records
- ClickHouse persistence → ClickHouse: writes
- Backfill runner → ClickHouse persistence: backfills through
- Ledger indexer → Enrichment publisher: publishes work
- Enrichment publisher → SQS: sends messages
- SQS → Enrichment worker: delivers records
- Enrichment worker → Enrichment logic: dispatches enrichment
- Enrichment logic → Metadata services: fetches metadata
- Enrichment logic → ClickHouse: writes side tables
- AWS runtime → REST API: hosts
- AWS runtime → Ledger indexer: hosts
- AWS runtime → Enrichment worker: hosts