# fuellabs/fuel-core architecture

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

- Interactive diagram: https://gitdiagram.com/fuellabs/fuel-core
- Repository: https://github.com/fuellabs/fuel-core

## Overview

Fuel Core is a blockchain node and GraphQL client. The principal user workflow is to launch a node, submit transactions through GraphQL, execute them, produce and import blocks, and persist chain state. The repository also contains networking, relaying, gas-price, compression, and a separate chaos-testing harness. The README documents the GraphQL endpoint, execution, and persistence; several service-to-service links below are dashed because their wiring was not shown in the sampled source.

Main entry points: [`crates/fuel-core/src/service.rs`](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/service.rs) (Node Service), [`bin/chaos-test/src/main.rs`](https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/main.rs) (Chaos Harness), [`crates/fuel-core/src/graphql_api/api_service.rs`](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/graphql_api/api_service.rs) (GraphQL Service), [`crates/fuel-core/src/database/storage.rs`](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/database/storage.rs) (Chain Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Node Runtime"]
  node_node_cli["Node CLI<br/>[main.rs]"]
  node_run_config["Run Configuration<br/>[run.rs]"]
  node_node_service["Node Service<br/>[service.rs]"]
  node_genesis["Genesis Setup<br/>[genesis.rs]"]
end

subgraph group_execution["Transaction Lifecycle"]
  node_executor["Transaction Executor<br/>[executor.rs]"]
  node_txpool["Transaction Pool"]
  node_block_producer["Block Production<br/>[service.rs]"]
  node_block_importer["Block Import<br/>[importer.rs]"]
end

subgraph group_interfaces["GraphQL Interface"]
  node_graphql_api["GraphQL Service<br/>[api_service.rs]"]
  node_graphql_schema["GraphQL Schema<br/>[schema.rs]"]
  node_graphql_queries["GraphQL Queries<br/>[query.rs]"]
  node_client["Rust Client<br/>[client.rs]"]
end

subgraph group_state["Chain State"]
  node_database[("Chain Database<br/>[storage.rs]")]
  node_structured_storage["Structured Storage"]
  node_graphql_storage["GraphQL Storage<br/>[storage.rs]"]
end

subgraph group_services["Node Services"]
  node_p2p["Peer Networking<br/>[service.rs]"]
  node_relayer["DA Relayer Storage<br/>[storage.rs]"]
  node_gas_price["Gas Price Service<br/>[lib.rs]"]
  node_compression["Block Compression<br/>[service.rs]"]
end

subgraph group_chaos["Chaos Testing"]
  node_chaos_main["Chaos Harness<br/>[main.rs]"]
  node_chaos_cluster["Test Cluster<br/>[cluster.rs]"]
  node_chaos_faults["Fault Scheduler<br/>[fault.rs]"]
  node_chaos_invariants["Invariant Checks<br/>[invariants.rs]"]
  node_chaos_proxy["Fault Proxy<br/>[proxy.rs]"]
  node_chaos_redis["Redis Server<br/>[redis_server.rs]"]
end

node_operator(("Node Operator"))

node_operator -.->|"launches"| node_node_cli
node_node_cli -.->|"dispatches"| node_run_config
node_run_config -.->|"starts"| node_node_service
node_node_service -.->|"initializes"| node_genesis
node_operator -.->|"submits transactions"| node_client
node_client -.->|"sends GraphQL"| node_graphql_api
node_graphql_api -.->|"serves"| node_graphql_schema
node_graphql_schema -.->|"routes queries"| node_graphql_queries
node_graphql_api -.->|"executes mutations"| node_executor
node_executor -.->|"submits transactions"| node_txpool
node_txpool -.->|"provides transactions"| node_block_producer
node_block_producer -.->|"produces blocks"| node_block_importer
node_block_importer -.->|"persists blocks"| node_database
node_database -.->|"uses"| node_structured_storage
node_graphql_queries -.->|"reads chain data"| node_graphql_storage
node_graphql_storage -.->|"reads state"| node_database
node_node_service -.->|"starts"| node_p2p
node_node_service -.->|"starts"| node_relayer
node_node_service -.->|"starts"| node_gas_price
node_node_service -.->|"starts"| node_compression
node_chaos_main -->|"creates"| node_chaos_cluster
node_chaos_main -->|"runs"| node_chaos_faults
node_chaos_main -->|"runs"| node_chaos_invariants
node_chaos_main -.->|"configures"| node_chaos_proxy
node_chaos_proxy -->|"uses"| node_chaos_redis

click node_node_cli "https://github.com/fuellabs/fuel-core/blob/master/bin/fuel-core/src/main.rs"
click node_run_config "https://github.com/fuellabs/fuel-core/blob/master/bin/fuel-core/src/cli/run.rs"
click node_node_service "https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/service.rs"
click node_genesis "https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/service/genesis.rs"
click node_graphql_api "https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/graphql_api/api_service.rs"
click node_graphql_schema "https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/schema.rs"
click node_graphql_queries "https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/query.rs"
click node_client "https://github.com/fuellabs/fuel-core/blob/master/crates/client/src/client.rs"
click node_executor "https://github.com/fuellabs/fuel-core/blob/master/crates/services/executor/src/executor.rs"
click node_txpool "https://github.com/fuellabs/fuel-core/tree/master/crates/services/txpool_v2"
click node_block_producer "https://github.com/fuellabs/fuel-core/blob/master/crates/services/consensus_module/poa/src/service.rs"
click node_block_importer "https://github.com/fuellabs/fuel-core/blob/master/crates/services/importer/src/importer.rs"
click node_database "https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/database/storage.rs"
click node_structured_storage "https://github.com/fuellabs/fuel-core/blob/master/crates/storage/src/structured_storage.rs"
click node_graphql_storage "https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/graphql_api/storage.rs"
click node_p2p "https://github.com/fuellabs/fuel-core/blob/master/crates/services/p2p/src/service.rs"
click node_relayer "https://github.com/fuellabs/fuel-core/blob/master/crates/services/relayer/src/storage.rs"
click node_gas_price "https://github.com/fuellabs/fuel-core/blob/master/crates/services/gas_price_service/src/lib.rs"
click node_compression "https://github.com/fuellabs/fuel-core/blob/master/crates/services/compression/src/service.rs"
click node_chaos_main "https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/main.rs"
click node_chaos_cluster "https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/cluster.rs"
click node_chaos_faults "https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/fault.rs"
click node_chaos_invariants "https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/invariants.rs"
click node_chaos_proxy "https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/proxy.rs"
click node_chaos_redis "https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/redis_server.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_node_cli,node_run_config,node_node_service,node_genesis toneBlue
class node_executor,node_txpool,node_block_producer,node_block_importer toneAmber
class node_graphql_api,node_graphql_schema,node_graphql_queries,node_client toneMint
class node_database,node_structured_storage,node_graphql_storage toneRose
class node_p2p,node_relayer,node_gas_price,node_compression,node_operator toneIndigo
class node_chaos_main,node_chaos_cluster,node_chaos_faults,node_chaos_invariants,node_chaos_proxy,node_chaos_redis toneTeal
```

## Components

### Node Runtime

- [Node CLI](https://github.com/fuellabs/fuel-core/blob/master/bin/fuel-core/src/main.rs): `bin/fuel-core/src/main.rs`
- [Run Configuration](https://github.com/fuellabs/fuel-core/blob/master/bin/fuel-core/src/cli/run.rs): `bin/fuel-core/src/cli/run.rs`
- [Node Service](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/service.rs): `crates/fuel-core/src/service.rs`
- [Genesis Setup](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/service/genesis.rs): `crates/fuel-core/src/service/genesis.rs`

### Transaction Lifecycle

- [Transaction Executor](https://github.com/fuellabs/fuel-core/blob/master/crates/services/executor/src/executor.rs): `crates/services/executor/src/executor.rs`
- [Transaction Pool](https://github.com/fuellabs/fuel-core/tree/master/crates/services/txpool_v2): `crates/services/txpool_v2`
- [Block Production](https://github.com/fuellabs/fuel-core/blob/master/crates/services/consensus_module/poa/src/service.rs): `crates/services/consensus_module/poa/src/service.rs`
- [Block Import](https://github.com/fuellabs/fuel-core/blob/master/crates/services/importer/src/importer.rs): `crates/services/importer/src/importer.rs`

### GraphQL Interface

- [GraphQL Service](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/graphql_api/api_service.rs): `crates/fuel-core/src/graphql_api/api_service.rs`
- [GraphQL Schema](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/schema.rs): `crates/fuel-core/src/schema.rs`
- [GraphQL Queries](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/query.rs): `crates/fuel-core/src/query.rs`
- [Rust Client](https://github.com/fuellabs/fuel-core/blob/master/crates/client/src/client.rs): `crates/client/src/client.rs`

### Chain State

- [Chain Database](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/database/storage.rs): `crates/fuel-core/src/database/storage.rs`
- [Structured Storage](https://github.com/fuellabs/fuel-core/blob/master/crates/storage/src/structured_storage.rs): `crates/storage/src/structured_storage.rs`
- [GraphQL Storage](https://github.com/fuellabs/fuel-core/blob/master/crates/fuel-core/src/graphql_api/storage.rs): `crates/fuel-core/src/graphql_api/storage.rs`

### Node Services

- [Peer Networking](https://github.com/fuellabs/fuel-core/blob/master/crates/services/p2p/src/service.rs): `crates/services/p2p/src/service.rs`
- [DA Relayer Storage](https://github.com/fuellabs/fuel-core/blob/master/crates/services/relayer/src/storage.rs): `crates/services/relayer/src/storage.rs`
- [Gas Price Service](https://github.com/fuellabs/fuel-core/blob/master/crates/services/gas_price_service/src/lib.rs): `crates/services/gas_price_service/src/lib.rs`
- [Block Compression](https://github.com/fuellabs/fuel-core/blob/master/crates/services/compression/src/service.rs): `crates/services/compression/src/service.rs`

### Chaos Testing

- [Chaos Harness](https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/main.rs): `bin/chaos-test/src/main.rs`
- [Test Cluster](https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/cluster.rs): `bin/chaos-test/src/cluster.rs`
- [Fault Scheduler](https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/fault.rs): `bin/chaos-test/src/fault.rs`
- [Invariant Checks](https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/invariants.rs): `bin/chaos-test/src/invariants.rs`
- [Fault Proxy](https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/proxy.rs): `bin/chaos-test/src/proxy.rs`
- [Redis Server](https://github.com/fuellabs/fuel-core/blob/master/bin/chaos-test/src/redis_server.rs): `bin/chaos-test/src/redis_server.rs`

### Other components

- **Node Operator**

## Connections

- Node Operator → Node CLI: launches (evidence: `README.md`)
- Node CLI → Run Configuration: dispatches
- Run Configuration → Node Service: starts
- Node Service → Genesis Setup: initializes
- Node Operator → Rust Client: submits transactions (evidence: `README.md`)
- Rust Client → GraphQL Service: sends GraphQL (evidence: `README.md`)
- GraphQL Service → GraphQL Schema: serves
- GraphQL Schema → GraphQL Queries: routes queries
- GraphQL Service → Transaction Executor: executes mutations (evidence: `README.md`)
- Transaction Executor → Transaction Pool: submits transactions
- Transaction Pool → Block Production: provides transactions
- Block Production → Block Import: produces blocks
- Block Import → Chain Database: persists blocks (evidence: `README.md`)
- Chain Database → Structured Storage: uses (evidence: `crates/fuel-core/src/database/storage.rs`)
- GraphQL Queries → GraphQL Storage: reads chain data
- GraphQL Storage → Chain Database: reads state
- Node Service → Peer Networking: starts
- Node Service → DA Relayer Storage: starts
- Node Service → Gas Price Service: starts
- Node Service → Block Compression: starts
- Chaos Harness → Test Cluster: creates (evidence: `bin/chaos-test/src/main.rs`)
- Chaos Harness → Fault Scheduler: runs (evidence: `bin/chaos-test/src/main.rs`)
- Chaos Harness → Invariant Checks: runs (evidence: `bin/chaos-test/src/main.rs`)
- Chaos Harness → Fault Proxy: configures (evidence: `bin/chaos-test/src/main.rs`)
- Fault Proxy → Redis Server: uses (evidence: `bin/chaos-test/src/proxy.rs`)
