# sevenlabs-hq/carbon architecture

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

- Interactive diagram: https://gitdiagram.com/sevenlabs-hq/carbon
- Repository: https://github.com/sevenlabs-hq/carbon

## Overview

Carbon is a Rust framework for Solana indexers: datasources supply live, historical, or snapshot updates; the core runtime filters and routes them through typed decoders to processors and sinks. The README documents this modular workflow and the Postgres, GraphQL, and metrics capabilities. The sampled pipeline excerpt confirms task-based datasource consumption and dispatch to update pipes; most datasource and decoder internals were not sampled, so their implementation-level links are not inferred.

Main entry points: [`crates/core/src/pipeline.rs`](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/pipeline.rs) (Pipeline runtime), [`datasources`](https://github.com/sevenlabs-hq/carbon/tree/main/datasources) (Datasource adapters), [`decoders/boop-decoder/src/lib.rs`](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/lib.rs) (Program decoders), [`crates/core/src/instruction.rs`](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/instruction.rs) (Instruction decoding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Data ingestion"]
  node_sources["Datasource adapters"]
  node_geyser["Geyser streams<br/>[lib.rs]"]
  node_rpc["RPC sources<br/>[lib.rs]"]
  node_history["Backfill and snapshots<br/>[lib.rs]"]
  node_adapter["Message adapters<br/>[lib.rs]"]
end

subgraph group_runtime["Core runtime"]
  node_pipeline["Pipeline runtime<br/>[pipeline.rs]"]
  node_filters["Update filters<br/>[filter.rs]"]
  node_instruction["Instruction decoding<br/>[instruction.rs]"]
  node_processor["Processors<br/>[processor.rs]"]
end

subgraph group_decoding["Decoding"]
  node_decoder["Program decoders<br/>[lib.rs]"]
  node_account_decode["Account decoding"]
  node_events["Event decoding<br/>[mod.rs]"]
end

subgraph group_outputs["Storage and outputs"]
  node_boop_rows["Boop Postgres rows"]
  node_boop_config_row["Config row<br/>[config_row.rs]"]
  node_boop_update_row["Config update row"]
  node_drift_rows["Drift Postgres rows"]
  node_postgres["Postgres processors<br/>[processors.rs]"]
  node_database[("Postgres database")]
end

subgraph group_query["Query and metrics"]
  node_graphql["GraphQL helpers<br/>[server.rs]"]
  node_graphql_queries["Decoder queries<br/>[query.rs]"]
  node_metrics["Pipeline metrics<br/>[metrics.rs]"]
  node_exporters["Metrics exporters<br/>[pipeline.rs]"]
  node_prometheus["Prometheus"]
end

node_indexer(("Indexer application"))

node_indexer -->|"configures"| node_pipeline
node_indexer -->|"selects"| node_sources
node_sources -->|"includes"| node_geyser
node_sources -->|"includes"| node_rpc
node_sources -->|"includes"| node_history
node_sources -->|"includes"| node_adapter
node_pipeline -->|"consumes updates"| node_sources
node_pipeline -->|"routes through"| node_filters
node_pipeline -->|"dispatches"| node_instruction
node_instruction -->|"decodes typed data"| node_decoder
node_decoder -->|"decodes accounts"| node_account_decode
node_decoder -->|"decodes events"| node_events
node_pipeline -->|"dispatches output"| node_processor
node_processor -->|"persists through"| node_postgres
node_postgres -->|"writes rows"| node_database
node_boop_rows -.->|"defines stored rows"| node_database
node_boop_config_row -.->|"defines stored rows"| node_database
node_boop_update_row -.->|"defines stored rows"| node_database
node_drift_rows -.->|"defines stored rows"| node_database
node_database -->|"queried by"| node_graphql_queries
node_graphql_queries -.->|"exposes query data"| node_graphql
node_indexer -->|"exposes indexed data"| node_graphql
node_pipeline -->|"registers metrics"| node_metrics
node_pipeline -->|"initializes exporters"| node_exporters
node_metrics -.->|"exports optionally"| node_prometheus

click node_sources "https://github.com/sevenlabs-hq/carbon/tree/main/datasources"
click node_geyser "https://github.com/sevenlabs-hq/carbon/blob/main/datasources/yellowstone-grpc-datasource/src/lib.rs"
click node_rpc "https://github.com/sevenlabs-hq/carbon/blob/main/datasources/rpc-block-subscribe-datasource/src/lib.rs"
click node_history "https://github.com/sevenlabs-hq/carbon/blob/main/datasources/validator-snapshot-datasource/src/lib.rs"
click node_adapter "https://github.com/sevenlabs-hq/carbon/blob/main/datasources/stream-message-datasource/src/lib.rs"
click node_pipeline "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/pipeline.rs"
click node_filters "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/filter.rs"
click node_instruction "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/instruction.rs"
click node_processor "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/processor.rs"
click node_decoder "https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/lib.rs"
click node_account_decode "https://github.com/sevenlabs-hq/carbon/blob/main/decoders/address-lookup-table-decoder/src/accounts/address_lookup_table.rs"
click node_events "https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/events/mod.rs"
click node_boop_rows "https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/accounts/postgres/bonding_curve_row.rs"
click node_boop_config_row "https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/accounts/postgres/config_row.rs"
click node_boop_update_row "https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/instructions/postgres/update_config_row.rs"
click node_drift_rows "https://github.com/sevenlabs-hq/carbon/tree/main/decoders/drift-v2-decoder/src/accounts/postgres"
click node_postgres "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/postgres/processors.rs"
click node_graphql "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/graphql/server.rs"
click node_graphql_queries "https://github.com/sevenlabs-hq/carbon/blob/main/decoders/drift-v2-decoder/src/graphql/query.rs"
click node_metrics "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/metrics.rs"
click node_exporters "https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/pipeline.rs"

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_sources,node_geyser,node_rpc,node_history,node_adapter toneBlue
class node_pipeline,node_filters,node_instruction,node_processor toneAmber
class node_decoder,node_account_decode,node_events toneMint
class node_boop_rows,node_boop_config_row,node_boop_update_row,node_drift_rows,node_postgres,node_database toneRose
class node_graphql,node_graphql_queries,node_metrics,node_exporters,node_prometheus,node_indexer toneIndigo
```

## Components

### Data ingestion

- [Datasource adapters](https://github.com/sevenlabs-hq/carbon/tree/main/datasources): `datasources`
- [Geyser streams](https://github.com/sevenlabs-hq/carbon/blob/main/datasources/yellowstone-grpc-datasource/src/lib.rs): `datasources/yellowstone-grpc-datasource/src/lib.rs`
- [RPC sources](https://github.com/sevenlabs-hq/carbon/blob/main/datasources/rpc-block-subscribe-datasource/src/lib.rs): `datasources/rpc-block-subscribe-datasource/src/lib.rs`
- [Backfill and snapshots](https://github.com/sevenlabs-hq/carbon/blob/main/datasources/validator-snapshot-datasource/src/lib.rs): `datasources/validator-snapshot-datasource/src/lib.rs`
- [Message adapters](https://github.com/sevenlabs-hq/carbon/blob/main/datasources/stream-message-datasource/src/lib.rs): `datasources/stream-message-datasource/src/lib.rs`

### Core runtime

- [Pipeline runtime](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/pipeline.rs): `crates/core/src/pipeline.rs`
- [Update filters](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/filter.rs): `crates/core/src/filter.rs`
- [Instruction decoding](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/instruction.rs): `crates/core/src/instruction.rs`
- [Processors](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/processor.rs): `crates/core/src/processor.rs`

### Decoding

- [Program decoders](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/lib.rs): `decoders/boop-decoder/src/lib.rs`
- [Account decoding](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/address-lookup-table-decoder/src/accounts/address_lookup_table.rs): `decoders/address-lookup-table-decoder/src/accounts/address_lookup_table.rs`
- [Event decoding](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/events/mod.rs): `decoders/boop-decoder/src/events/mod.rs`

### Storage and outputs

- [Boop Postgres rows](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/accounts/postgres/bonding_curve_row.rs): `decoders/boop-decoder/src/accounts/postgres/bonding_curve_row.rs`
- [Config row](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/accounts/postgres/config_row.rs): `decoders/boop-decoder/src/accounts/postgres/config_row.rs`
- [Config update row](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/boop-decoder/src/instructions/postgres/update_config_row.rs): `decoders/boop-decoder/src/instructions/postgres/update_config_row.rs`
- [Drift Postgres rows](https://github.com/sevenlabs-hq/carbon/tree/main/decoders/drift-v2-decoder/src/accounts/postgres): `decoders/drift-v2-decoder/src/accounts/postgres`
- [Postgres processors](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/postgres/processors.rs): `crates/core/src/postgres/processors.rs`
- **Postgres database**

### Query and metrics

- [GraphQL helpers](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/graphql/server.rs): `crates/core/src/graphql/server.rs`
- [Decoder queries](https://github.com/sevenlabs-hq/carbon/blob/main/decoders/drift-v2-decoder/src/graphql/query.rs): `decoders/drift-v2-decoder/src/graphql/query.rs`
- [Pipeline metrics](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/metrics.rs): `crates/core/src/metrics.rs`
- [Metrics exporters](https://github.com/sevenlabs-hq/carbon/blob/main/crates/core/src/pipeline.rs): `crates/core/src/pipeline.rs`
- **Prometheus**

### Other components

- **Indexer application**

## Connections

- Indexer application → Pipeline runtime: configures
- Indexer application → Datasource adapters: selects
- Datasource adapters → Geyser streams: includes
- Datasource adapters → RPC sources: includes
- Datasource adapters → Backfill and snapshots: includes
- Datasource adapters → Message adapters: includes
- Pipeline runtime → Datasource adapters: consumes updates (evidence: `crates/core/src/pipeline.rs`)
- Pipeline runtime → Update filters: routes through
- Pipeline runtime → Instruction decoding: dispatches (evidence: `crates/core/src/pipeline.rs`)
- Instruction decoding → Program decoders: decodes typed data
- Program decoders → Account decoding: decodes accounts
- Program decoders → Event decoding: decodes events
- Pipeline runtime → Processors: dispatches output
- Processors → Postgres processors: persists through (evidence: `crates/core/src/postgres/processors.rs`)
- Postgres processors → Postgres database: writes rows
- Boop Postgres rows → Postgres database: defines stored rows
- Config row → Postgres database: defines stored rows
- Config update row → Postgres database: defines stored rows
- Drift Postgres rows → Postgres database: defines stored rows
- Postgres database → Decoder queries: queried by (evidence: `decoders/drift-v2-decoder/src/graphql/query.rs`)
- Decoder queries → GraphQL helpers: exposes query data
- Indexer application → GraphQL helpers: exposes indexed data
- Pipeline runtime → Pipeline metrics: registers metrics (evidence: `crates/core/src/pipeline.rs`)
- Pipeline runtime → Metrics exporters: initializes exporters (evidence: `crates/core/src/pipeline.rs`)
- Pipeline metrics → Prometheus: exports optionally
