# paritytech/polkadot-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/paritytech/polkadot-sdk
- Repository: https://github.com/paritytech/polkadot-sdk

## Overview

The Polkadot SDK is a toolkit for building blockchain runtimes and nodes, including parachains and cross-chain bridges. A principal interoperability workflow is relaying finalized headers and messages between chains: relay commands select the operation, relay components handle chain access and synchronization, and bridge pallets verify and process updates. The tree also shows Snowbridge’s Ethereum-facing queues and beacon verification, plus Cumulus parachain services. The README describes the SDK’s broader scope; sampled source is sparse, so links between most listed subsystems are intentionally omitted.

Main entry points: [`bridges/relays/lib-substrate-relay/src/cli/mod.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/lib-substrate-relay/src/cli/mod.rs) (Relay commands), [`bridges/relays/finality/src/finality_loop.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/finality/src/finality_loop.rs) (Finality sync), [`bridges/relays/messages/src/message_lane_loop.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/messages/src/message_lane_loop.rs) (Message sync), [`bridges/relays/parachains/src/parachains_loop.rs`](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/parachains/src/parachains_loop.rs) (Parachain sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime building blocks"]
  node_runtime_primitives["Runtime primitives<br/>[lib.rs]"]
end

subgraph group_bridges["Bridge runtime"]
  node_header_bridge["Header-chain bridge<br/>[lib.rs]"]
  node_parachain_bridge["Parachain bridge<br/>[lib.rs]"]
  node_message_bridge["Message lanes<br/>[lib.rs]"]
  node_relayer_registry["Relayer registry<br/>[lib.rs]"]
  node_xcm_hub["XCM bridge hub<br/>[lib.rs]"]
  node_hub_router["Hub router<br/>[lib.rs]"]
  node_ethereum_client["Ethereum light client<br/>[lib.rs]"]
  node_inbound_queue["Inbound queue<br/>[lib.rs]"]
  node_outbound_queue["Outbound queue<br/>[lib.rs]"]
  node_beacon_primitives["Beacon verification<br/>[lib.rs]"]
end

subgraph group_relays["Relay services"]
  node_relay_cli["Relay commands<br/>[mod.rs]"]
  node_substrate_client["Chain client<br/>[mod.rs]"]
  node_finality_sync["Finality sync<br/>[finality_loop.rs]"]
  node_message_sync["Message sync"]
  node_parachain_sync["Parachain sync<br/>[parachains_loop.rs]"]
end

subgraph group_cumulus["Parachain services"]
  node_collator["Collator service<br/>[service.rs]"]
  node_aura_consensus["Aura consensus<br/>[lib.rs]"]
  node_para_system["Parachain system<br/>[lib.rs]"]
  node_relay_interface["Relay-chain interface<br/>[lib.rs]"]
end

node_developer(("Chain developer"))

node_developer -->|"runs commands"| node_relay_cli
node_finality_sync -->|"accesses chains"| node_substrate_client
node_message_sync -->|"accesses chains"| node_substrate_client
node_parachain_sync -->|"accesses chains"| node_substrate_client
node_relay_cli -->|"starts sync"| node_finality_sync
node_relay_cli -->|"starts sync"| node_message_sync
node_relay_cli -->|"starts sync"| node_parachain_sync
node_finality_sync -->|"submits proofs"| node_header_bridge
node_message_sync -->|"relays messages"| node_message_bridge
node_parachain_sync -->|"relays proofs"| node_parachain_bridge
node_ethereum_client -->|"verifies updates"| node_beacon_primitives
node_collator -->|"uses consensus"| node_aura_consensus
node_collator -->|"connects to relay"| node_relay_interface
node_para_system -->|"uses relay data"| node_relay_interface
node_developer -->|"builds with"| node_runtime_primitives

click node_runtime_primitives "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/primitives/runtime/src/lib.rs"
click node_header_bridge "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/grandpa/src/lib.rs"
click node_parachain_bridge "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/parachains/src/lib.rs"
click node_message_bridge "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/messages/src/lib.rs"
click node_relayer_registry "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/relayers/src/lib.rs"
click node_xcm_hub "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/xcm-bridge-hub/src/lib.rs"
click node_hub_router "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/xcm-bridge-hub-router/src/lib.rs"
click node_relay_cli "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/lib-substrate-relay/src/cli/mod.rs"
click node_substrate_client "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/client-substrate/src/client/mod.rs"
click node_finality_sync "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/finality/src/finality_loop.rs"
click node_message_sync "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/messages/src/message_lane_loop.rs"
click node_parachain_sync "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/parachains/src/parachains_loop.rs"
click node_ethereum_client "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/pallets/ethereum-client/src/lib.rs"
click node_inbound_queue "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/pallets/inbound-queue/src/lib.rs"
click node_outbound_queue "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/pallets/outbound-queue/src/lib.rs"
click node_beacon_primitives "https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/primitives/beacon/src/lib.rs"
click node_collator "https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/client/collator/src/service.rs"
click node_aura_consensus "https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/client/consensus/aura/src/lib.rs"
click node_para_system "https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/pallets/parachain-system/src/lib.rs"
click node_relay_interface "https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/client/relay-chain-interface/src/lib.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_runtime_primitives toneBlue
class node_header_bridge,node_parachain_bridge,node_message_bridge,node_relayer_registry,node_xcm_hub,node_hub_router,node_ethereum_client,node_inbound_queue,node_outbound_queue,node_beacon_primitives toneAmber
class node_relay_cli,node_substrate_client,node_finality_sync,node_message_sync,node_parachain_sync toneMint
class node_collator,node_aura_consensus,node_para_system,node_relay_interface toneRose
class node_developer toneIndigo
```

## Components

### Runtime building blocks

- [Runtime primitives](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/primitives/runtime/src/lib.rs): `bridges/primitives/runtime/src/lib.rs`

### Bridge runtime

- [Header-chain bridge](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/grandpa/src/lib.rs): `bridges/modules/grandpa/src/lib.rs`
- [Parachain bridge](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/parachains/src/lib.rs): `bridges/modules/parachains/src/lib.rs`
- [Message lanes](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/messages/src/lib.rs): `bridges/modules/messages/src/lib.rs`
- [Relayer registry](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/relayers/src/lib.rs): `bridges/modules/relayers/src/lib.rs`
- [XCM bridge hub](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/xcm-bridge-hub/src/lib.rs): `bridges/modules/xcm-bridge-hub/src/lib.rs`
- [Hub router](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/modules/xcm-bridge-hub-router/src/lib.rs): `bridges/modules/xcm-bridge-hub-router/src/lib.rs`
- [Ethereum light client](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/pallets/ethereum-client/src/lib.rs): `bridges/snowbridge/pallets/ethereum-client/src/lib.rs`
- [Inbound queue](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/pallets/inbound-queue/src/lib.rs): `bridges/snowbridge/pallets/inbound-queue/src/lib.rs`
- [Outbound queue](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/pallets/outbound-queue/src/lib.rs): `bridges/snowbridge/pallets/outbound-queue/src/lib.rs`
- [Beacon verification](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/snowbridge/primitives/beacon/src/lib.rs): `bridges/snowbridge/primitives/beacon/src/lib.rs`

### Relay services

- [Relay commands](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/lib-substrate-relay/src/cli/mod.rs): `bridges/relays/lib-substrate-relay/src/cli/mod.rs`
- [Chain client](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/client-substrate/src/client/mod.rs): `bridges/relays/client-substrate/src/client/mod.rs`
- [Finality sync](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/finality/src/finality_loop.rs): `bridges/relays/finality/src/finality_loop.rs`
- [Message sync](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/messages/src/message_lane_loop.rs): `bridges/relays/messages/src/message_lane_loop.rs`
- [Parachain sync](https://github.com/paritytech/polkadot-sdk/blob/master/bridges/relays/parachains/src/parachains_loop.rs): `bridges/relays/parachains/src/parachains_loop.rs`

### Parachain services

- [Collator service](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/client/collator/src/service.rs): `cumulus/client/collator/src/service.rs`
- [Aura consensus](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/client/consensus/aura/src/lib.rs): `cumulus/client/consensus/aura/src/lib.rs`
- [Parachain system](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/pallets/parachain-system/src/lib.rs): `cumulus/pallets/parachain-system/src/lib.rs`
- [Relay-chain interface](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/client/relay-chain-interface/src/lib.rs): `cumulus/client/relay-chain-interface/src/lib.rs`

### Other components

- **Chain developer**

## Connections

- Chain developer → Relay commands: runs commands
- Finality sync → Chain client: accesses chains
- Message sync → Chain client: accesses chains
- Parachain sync → Chain client: accesses chains
- Relay commands → Finality sync: starts sync
- Relay commands → Message sync: starts sync
- Relay commands → Parachain sync: starts sync
- Finality sync → Header-chain bridge: submits proofs
- Message sync → Message lanes: relays messages
- Parachain sync → Parachain bridge: relays proofs
- Ethereum light client → Beacon verification: verifies updates
- Collator service → Aura consensus: uses consensus
- Collator service → Relay-chain interface: connects to relay
- Parachain system → Relay-chain interface: uses relay data
- Chain developer → Runtime primitives: builds with
