# dfinity/ic architecture

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

- Interactive diagram: https://gitdiagram.com/dfinity/ic
- Repository: https://github.com/dfinity/ic

## Overview

This is the Internet Computer Protocol repository; its central product is the Rust replica run by machines in the network. The principal workflow is user requests entering the replica, being handled as queries or state-changing execution, and interacting with replicated state. The tree and README establish the product scope, while sampled source and the SOURCE INDEX support only selected internal links. Consequently, several protocol-stage connections are shown as unverified rather than asserted as observed calls.

Main entry points: [`rs/replica/bin/replica/main.rs`](https://github.com/dfinity/ic/blob/master/rs/replica/bin/replica/main.rs) (Replica process), [`rs/execution_environment/src/execution_environment.rs`](https://github.com/dfinity/ic/blob/master/rs/execution_environment/src/execution_environment.rs) (Execution environment), [`rs/consensus`](https://github.com/dfinity/ic/tree/master/rs/consensus) (Consensus), [`rs/canister_sandbox/src/replica_controller/sandboxed_execution_controller.rs`](https://github.com/dfinity/ic/blob/master/rs/canister_sandbox/src/replica_controller/sandboxed_execution_controller.rs) (Sandbox controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_replica["Replica runtime"]
  node_replica_bin["Replica process<br/>[main.rs]"]
  node_execution["Execution environment"]
  node_query_handler["Query handler<br/>[query_handler.rs]"]
  node_query_context["Query context<br/>[query_context.rs]"]
  node_sandbox_controller["Sandbox controller"]
  node_sandbox_rpc["Sandbox RPC<br/>[rpc.rs]"]
  node_sandbox_ids["Sandbox identifiers<br/>[id.rs]"]
end

subgraph group_consensus["Consensus and networking"]
  node_consensus_core["Consensus"]
  node_p2p["Peer networking"]
  node_bitcoin_consensus["Bitcoin consensus<br/>[lib.rs]"]
end

subgraph group_state["Replicated state"]
  node_replicated_state[("Replicated state")]
  node_page_storage[("Page storage<br/>[storage.rs]")]
end

subgraph group_services["Canister services"]
  node_registry["Registry canister<br/>[registry.rs]"]
  node_registry_storage[("Registry storage<br/>[storage.rs]")]
  node_nns_governance[("NNS governance<br/>[storage.rs]")]
  node_sns_extensions["SNS extensions<br/>[extensions.rs]"]
  node_boundary_node["Boundary node<br/>[main.rs]"]
  node_pocket_ic["Pocket IC<br/>[pocket_ic.rs]"]
end

subgraph group_bitcoin["Bitcoin integration"]
  node_ckbtc_state[("ckBTC minter state<br/>[state.rs]")]
  node_ckbtc_events[("Minter event log<br/>[eventlog.rs]")]
  node_ckbtc_storage[("Minter stable storage<br/>[storage.rs]")]
  node_ckbtc_tx["Bitcoin transactions<br/>[tx.rs]"]
end

node_users(("Users"))
node_bitcoin_network(("Bitcoin network"))

node_users -.->|"submit requests"| node_replica_bin
node_replica_bin -.->|"dispatches execution"| node_execution
node_execution -.->|"handles queries"| node_query_handler
node_query_handler -->|"uses context"| node_query_context
node_replica_bin -.->|"runs protocol"| node_consensus_core
node_consensus_core -.->|"communicates over"| node_p2p
node_execution -.->|"uses state"| node_replicated_state
node_page_storage -->|"persists pages"| node_replicated_state
node_registry -->|"uses storage"| node_registry_storage
node_replica_bin -.->|"serves through"| node_boundary_node
node_sandbox_controller -->|"uses RPC"| node_sandbox_rpc
node_sandbox_controller -->|"uses identifiers"| node_sandbox_ids
node_replica_bin -.->|"delegates execution"| node_sandbox_controller
node_consensus_core -.->|"integrates Bitcoin"| node_bitcoin_consensus
node_ckbtc_state -->|"replays events"| node_ckbtc_events
node_ckbtc_storage -->|"stores events"| node_ckbtc_events
node_ckbtc_tx -.->|"creates transactions"| node_bitcoin_network
node_ckbtc_state -->|"tracks transactions"| node_ckbtc_tx
node_pocket_ic -.->|"runs replica-like tests"| node_replica_bin

click node_replica_bin "https://github.com/dfinity/ic/blob/master/rs/replica/bin/replica/main.rs"
click node_execution "https://github.com/dfinity/ic/blob/master/rs/execution_environment/src/execution_environment.rs"
click node_query_handler "https://github.com/dfinity/ic/blob/master/rs/execution_environment/src/query_handler.rs"
click node_query_context "https://github.com/dfinity/ic/blob/master/rs/execution_environment/src/query_handler/query_context.rs"
click node_consensus_core "https://github.com/dfinity/ic/tree/master/rs/consensus"
click node_p2p "https://github.com/dfinity/ic/tree/master/rs/p2p"
click node_bitcoin_consensus "https://github.com/dfinity/ic/blob/master/rs/bitcoin/consensus/src/lib.rs"
click node_replicated_state "https://github.com/dfinity/ic/tree/master/rs/replicated_state"
click node_page_storage "https://github.com/dfinity/ic/blob/master/rs/replicated_state/src/page_map/storage.rs"
click node_registry "https://github.com/dfinity/ic/blob/master/rs/registry/canister/src/registry.rs"
click node_registry_storage "https://github.com/dfinity/ic/blob/master/rs/registry/canister/src/storage.rs"
click node_nns_governance "https://github.com/dfinity/ic/blob/master/rs/nns/governance/src/storage.rs"
click node_sns_extensions "https://github.com/dfinity/ic/blob/master/rs/sns/governance/src/extensions.rs"
click node_boundary_node "https://github.com/dfinity/ic/blob/master/rs/boundary_node/ic_boundary/src/main.rs"
click node_pocket_ic "https://github.com/dfinity/ic/blob/master/rs/pocket_ic_server/src/pocket_ic.rs"
click node_sandbox_controller "https://github.com/dfinity/ic/blob/master/rs/canister_sandbox/src/replica_controller/sandboxed_execution_controller.rs"
click node_sandbox_rpc "https://github.com/dfinity/ic/blob/master/rs/canister_sandbox/src/rpc.rs"
click node_sandbox_ids "https://github.com/dfinity/ic/blob/master/rs/canister_sandbox/src/protocol/id.rs"
click node_ckbtc_state "https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/state.rs"
click node_ckbtc_events "https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/state/eventlog.rs"
click node_ckbtc_storage "https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/storage.rs"
click node_ckbtc_tx "https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/tx.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_replica_bin,node_execution,node_query_handler,node_query_context,node_sandbox_controller,node_sandbox_rpc,node_sandbox_ids,node_users toneBlue
class node_consensus_core,node_p2p,node_bitcoin_consensus toneAmber
class node_replicated_state,node_page_storage toneMint
class node_registry,node_registry_storage,node_nns_governance,node_sns_extensions,node_boundary_node,node_pocket_ic toneRose
class node_ckbtc_state,node_ckbtc_events,node_ckbtc_storage,node_ckbtc_tx,node_bitcoin_network toneIndigo
```

## Components

### Replica runtime

- [Replica process](https://github.com/dfinity/ic/blob/master/rs/replica/bin/replica/main.rs): `rs/replica/bin/replica/main.rs`
- [Execution environment](https://github.com/dfinity/ic/blob/master/rs/execution_environment/src/execution_environment.rs): `rs/execution_environment/src/execution_environment.rs`
- [Query handler](https://github.com/dfinity/ic/blob/master/rs/execution_environment/src/query_handler.rs): `rs/execution_environment/src/query_handler.rs`
- [Query context](https://github.com/dfinity/ic/blob/master/rs/execution_environment/src/query_handler/query_context.rs): `rs/execution_environment/src/query_handler/query_context.rs`
- [Sandbox controller](https://github.com/dfinity/ic/blob/master/rs/canister_sandbox/src/replica_controller/sandboxed_execution_controller.rs): `rs/canister_sandbox/src/replica_controller/sandboxed_execution_controller.rs`
- [Sandbox RPC](https://github.com/dfinity/ic/blob/master/rs/canister_sandbox/src/rpc.rs): `rs/canister_sandbox/src/rpc.rs`
- [Sandbox identifiers](https://github.com/dfinity/ic/blob/master/rs/canister_sandbox/src/protocol/id.rs): `rs/canister_sandbox/src/protocol/id.rs`

### Consensus and networking

- [Consensus](https://github.com/dfinity/ic/tree/master/rs/consensus): `rs/consensus`
- [Peer networking](https://github.com/dfinity/ic/tree/master/rs/p2p): `rs/p2p`
- [Bitcoin consensus](https://github.com/dfinity/ic/blob/master/rs/bitcoin/consensus/src/lib.rs): `rs/bitcoin/consensus/src/lib.rs`

### Replicated state

- [Replicated state](https://github.com/dfinity/ic/tree/master/rs/replicated_state): `rs/replicated_state`
- [Page storage](https://github.com/dfinity/ic/blob/master/rs/replicated_state/src/page_map/storage.rs): `rs/replicated_state/src/page_map/storage.rs`

### Canister services

- [Registry canister](https://github.com/dfinity/ic/blob/master/rs/registry/canister/src/registry.rs): `rs/registry/canister/src/registry.rs`
- [Registry storage](https://github.com/dfinity/ic/blob/master/rs/registry/canister/src/storage.rs): `rs/registry/canister/src/storage.rs`
- [NNS governance](https://github.com/dfinity/ic/blob/master/rs/nns/governance/src/storage.rs): `rs/nns/governance/src/storage.rs`
- [SNS extensions](https://github.com/dfinity/ic/blob/master/rs/sns/governance/src/extensions.rs): `rs/sns/governance/src/extensions.rs`
- [Boundary node](https://github.com/dfinity/ic/blob/master/rs/boundary_node/ic_boundary/src/main.rs): `rs/boundary_node/ic_boundary/src/main.rs`
- [Pocket IC](https://github.com/dfinity/ic/blob/master/rs/pocket_ic_server/src/pocket_ic.rs): `rs/pocket_ic_server/src/pocket_ic.rs`

### Bitcoin integration

- [ckBTC minter state](https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/state.rs): `rs/bitcoin/ckbtc/minter/src/state.rs`
- [Minter event log](https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/state/eventlog.rs): `rs/bitcoin/ckbtc/minter/src/state/eventlog.rs`
- [Minter stable storage](https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/storage.rs): `rs/bitcoin/ckbtc/minter/src/storage.rs`
- [Bitcoin transactions](https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/src/tx.rs): `rs/bitcoin/ckbtc/minter/src/tx.rs`

### Other components

- **Users**
- **Bitcoin network**

## Connections

- Users → Replica process: submit requests
- Replica process → Execution environment: dispatches execution
- Execution environment → Query handler: handles queries (evidence: `rs/execution_environment/src/query_handler.rs`)
- Query handler → Query context: uses context (evidence: `rs/execution_environment/src/query_handler.rs`)
- Replica process → Consensus: runs protocol
- Consensus → Peer networking: communicates over
- Execution environment → Replicated state: uses state
- Page storage → Replicated state: persists pages (evidence: `rs/replicated_state/src/page_map/storage.rs`)
- Registry canister → Registry storage: uses storage (evidence: `rs/registry/canister/src/storage.rs`)
- Replica process → Boundary node: serves through
- Sandbox controller → Sandbox RPC: uses RPC (evidence: `rs/canister_sandbox/src/replica_controller/sandboxed_execution_controller.rs`)
- Sandbox controller → Sandbox identifiers: uses identifiers (evidence: `rs/canister_sandbox/src/replica_controller/sandboxed_execution_controller.rs`)
- Replica process → Sandbox controller: delegates execution
- Consensus → Bitcoin consensus: integrates Bitcoin
- ckBTC minter state → Minter event log: replays events (evidence: `rs/bitcoin/ckbtc/minter/src/state/eventlog.rs`)
- Minter stable storage → Minter event log: stores events (evidence: `rs/bitcoin/ckbtc/minter/src/storage.rs`)
- Bitcoin transactions → Bitcoin network: creates transactions
- ckBTC minter state → Bitcoin transactions: tracks transactions (evidence: `rs/bitcoin/ckbtc/minter/src/state.rs`)
- Pocket IC → Replica process: runs replica-like tests
