# chuck-ie/order-book architecture

> Architecture diagram of the GitHub repository chuck-ie/order-book, 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/chuck-ie/order-book
- Repository: https://github.com/chuck-ie/order-book

## Overview

This Rust library implements several limit-order matching engines, exposing order placement, cancellation, matching, best-price and volume queries. Its main workflow is a caller submitting a place or cancel command to a matcher, which updates a price-level book and, for arena-backed variants, uses shared arena storage. The repository also provides bounded concurrent channels and an explicit benchmark-and-charting capability. Engine behavior is sampled for selected versions; the README documents the variants and performance comparisons, but benchmark runner wiring is only partially sampled.

Main entry points: [`src/common.rs`](https://github.com/chuck-ie/order-book/blob/main/src/common.rs) (Matcher API), [`src/slot_map/mod.rs`](https://github.com/chuck-ie/order-book/blob/main/src/slot_map/mod.rs) (Slot-map API), [`src/channel/mod.rs`](https://github.com/chuck-ie/order-book/blob/main/src/channel/mod.rs) (Channel API), [`src/engine/v4_sm_arena/matcher.rs`](https://github.com/chuck-ie/order-book/blob/main/src/engine/v4_sm_arena/matcher.rs) (V4 matcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_matching["Matching engines"]
  node_common_api["Matcher API<br/>[common.rs]"]
  node_engine_types["Order types<br/>[mod.rs]"]
  node_v1_matcher["V1 matcher<br/>[matcher.rs]"]
  node_v1_book["V1 Vec book<br/>[book.rs]"]
  node_v2_matcher["V2 matcher<br/>[matcher.rs]"]
  node_v2_book["V2 BTree book<br/>[book.rs]"]
  node_v3_matcher["V3 matcher<br/>[matcher.rs]"]
  node_v3_book["V3 slot-map book<br/>[book.rs]"]
  node_v4_matcher["V4 matcher<br/>[matcher.rs]"]
  node_v4_book["V4 arena book<br/>[book.rs]"]
  node_v5_matcher["V5 matcher<br/>[matcher.rs]"]
  node_v5_book["V5 indexed book<br/>[book.rs]"]
  node_arena_matcher_api["Arena matcher API"]
end

subgraph group_storage["Storage"]
  node_arena["Arena allocator<br/>[arena_allocator.rs]"]
  node_slot_map_api["Slot-map API<br/>[mod.rs]"]
  node_slot_standard["Standard slot map<br/>[standard.rs]"]
  node_slot_optimized["Optimized slot map<br/>[optimized.rs]"]
  node_slot_chunked["Chunked slots<br/>[chunked.rs]"]
end

subgraph group_channels["Channels"]
  node_channel_api["Channel API<br/>[mod.rs]"]
  node_ring_buffer["Ring buffer<br/>[ring_buffer.rs]"]
  node_producer["Producers<br/>[producer.rs]"]
  node_consumer["Consumers<br/>[consumer.rs]"]
end

subgraph group_benchmarking["Benchmarking"]
  node_bench_harness["Engine benchmarks<br/>[bench_engine.rs]"]
  node_bench_charts["Result charts<br/>[create_charts.rs]"]
end

node_caller(("Library caller"))

node_caller -->|"submits commands"| node_common_api
node_common_api -->|"dispatches"| node_v1_matcher
node_common_api -->|"dispatches"| node_v2_matcher
node_common_api -->|"dispatches"| node_v3_matcher
node_common_api -->|"dispatches"| node_v4_matcher
node_common_api -->|"dispatches"| node_v5_matcher
node_v1_matcher -->|"updates and queries"| node_v1_book
node_v2_matcher -->|"updates and queries"| node_v2_book
node_v3_matcher -->|"updates and queries"| node_v3_book
node_v4_matcher -->|"updates and queries"| node_v4_book
node_v5_matcher -->|"updates and queries"| node_v5_book
node_v4_matcher -->|"allocates and accesses"| node_arena
node_v5_matcher -->|"allocates and accesses"| node_arena
node_v4_book -->|"stores orders"| node_slot_chunked
node_v5_book -->|"stores orders"| node_slot_chunked
node_arena_matcher_api -->|"accepts arena"| node_arena
node_slot_map_api -->|"defines implementations"| node_slot_standard
node_slot_map_api -->|"defines implementations"| node_slot_optimized
node_slot_map_api -->|"defines implementations"| node_slot_chunked
node_channel_api -->|"constructs"| node_ring_buffer
node_channel_api -->|"exposes"| node_producer
node_channel_api -->|"exposes"| node_consumer
node_producer -->|"writes items"| node_ring_buffer
node_consumer -->|"reads items"| node_ring_buffer
node_bench_harness -->|"benchmarks engines"| node_common_api
node_bench_harness -->|"benchmarks arena engines"| node_arena_matcher_api
node_bench_charts -.->|"visualizes results"| node_bench_harness

click node_common_api "https://github.com/chuck-ie/order-book/blob/main/src/common.rs"
click node_engine_types "https://github.com/chuck-ie/order-book/blob/main/src/engine/mod.rs"
click node_v1_matcher "https://github.com/chuck-ie/order-book/blob/main/src/engine/v1_vec_only/matcher.rs"
click node_v1_book "https://github.com/chuck-ie/order-book/blob/main/src/engine/v1_vec_only/book.rs"
click node_v2_matcher "https://github.com/chuck-ie/order-book/blob/main/src/engine/v2_btree/matcher.rs"
click node_v2_book "https://github.com/chuck-ie/order-book/blob/main/src/engine/v2_btree/book.rs"
click node_v3_matcher "https://github.com/chuck-ie/order-book/blob/main/src/engine/v3_slot_map/matcher.rs"
click node_v3_book "https://github.com/chuck-ie/order-book/blob/main/src/engine/v3_slot_map/book.rs"
click node_v4_matcher "https://github.com/chuck-ie/order-book/blob/main/src/engine/v4_sm_arena/matcher.rs"
click node_v4_book "https://github.com/chuck-ie/order-book/blob/main/src/engine/v4_sm_arena/book.rs"
click node_v5_matcher "https://github.com/chuck-ie/order-book/blob/main/src/engine/v5_sm_arena_vec_index/matcher.rs"
click node_v5_book "https://github.com/chuck-ie/order-book/blob/main/src/engine/v5_sm_arena_vec_index/book.rs"
click node_arena_matcher_api "https://github.com/chuck-ie/order-book/blob/main/src/engine/arena_order_matcher.rs"
click node_arena "https://github.com/chuck-ie/order-book/blob/main/src/arena_allocator.rs"
click node_slot_map_api "https://github.com/chuck-ie/order-book/blob/main/src/slot_map/mod.rs"
click node_slot_standard "https://github.com/chuck-ie/order-book/blob/main/src/slot_map/standard.rs"
click node_slot_optimized "https://github.com/chuck-ie/order-book/blob/main/src/slot_map/optimized.rs"
click node_slot_chunked "https://github.com/chuck-ie/order-book/blob/main/src/slot_map/chunked.rs"
click node_channel_api "https://github.com/chuck-ie/order-book/blob/main/src/channel/mod.rs"
click node_ring_buffer "https://github.com/chuck-ie/order-book/blob/main/src/channel/ring_buffer.rs"
click node_producer "https://github.com/chuck-ie/order-book/blob/main/src/channel/producer.rs"
click node_consumer "https://github.com/chuck-ie/order-book/blob/main/src/channel/consumer.rs"
click node_bench_harness "https://github.com/chuck-ie/order-book/blob/main/benches/shared/bench_engine.rs"
click node_bench_charts "https://github.com/chuck-ie/order-book/blob/main/benches/create_charts.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_common_api,node_engine_types,node_v1_matcher,node_v1_book,node_v2_matcher,node_v2_book,node_v3_matcher,node_v3_book,node_v4_matcher,node_v4_book,node_v5_matcher,node_v5_book,node_arena_matcher_api toneBlue
class node_arena,node_slot_map_api,node_slot_standard,node_slot_optimized,node_slot_chunked toneAmber
class node_channel_api,node_ring_buffer,node_producer,node_consumer toneMint
class node_bench_harness,node_bench_charts toneRose
class node_caller toneIndigo
```

## Components

### Matching engines

- [Matcher API](https://github.com/chuck-ie/order-book/blob/main/src/common.rs): `src/common.rs`
- [Order types](https://github.com/chuck-ie/order-book/blob/main/src/engine/mod.rs): `src/engine/mod.rs`
- [V1 matcher](https://github.com/chuck-ie/order-book/blob/main/src/engine/v1_vec_only/matcher.rs): `src/engine/v1_vec_only/matcher.rs`
- [V1 Vec book](https://github.com/chuck-ie/order-book/blob/main/src/engine/v1_vec_only/book.rs): `src/engine/v1_vec_only/book.rs`
- [V2 matcher](https://github.com/chuck-ie/order-book/blob/main/src/engine/v2_btree/matcher.rs): `src/engine/v2_btree/matcher.rs`
- [V2 BTree book](https://github.com/chuck-ie/order-book/blob/main/src/engine/v2_btree/book.rs): `src/engine/v2_btree/book.rs`
- [V3 matcher](https://github.com/chuck-ie/order-book/blob/main/src/engine/v3_slot_map/matcher.rs): `src/engine/v3_slot_map/matcher.rs`
- [V3 slot-map book](https://github.com/chuck-ie/order-book/blob/main/src/engine/v3_slot_map/book.rs): `src/engine/v3_slot_map/book.rs`
- [V4 matcher](https://github.com/chuck-ie/order-book/blob/main/src/engine/v4_sm_arena/matcher.rs): `src/engine/v4_sm_arena/matcher.rs`
- [V4 arena book](https://github.com/chuck-ie/order-book/blob/main/src/engine/v4_sm_arena/book.rs): `src/engine/v4_sm_arena/book.rs`
- [V5 matcher](https://github.com/chuck-ie/order-book/blob/main/src/engine/v5_sm_arena_vec_index/matcher.rs): `src/engine/v5_sm_arena_vec_index/matcher.rs`
- [V5 indexed book](https://github.com/chuck-ie/order-book/blob/main/src/engine/v5_sm_arena_vec_index/book.rs): `src/engine/v5_sm_arena_vec_index/book.rs`
- [Arena matcher API](https://github.com/chuck-ie/order-book/blob/main/src/engine/arena_order_matcher.rs): `src/engine/arena_order_matcher.rs`

### Storage

- [Arena allocator](https://github.com/chuck-ie/order-book/blob/main/src/arena_allocator.rs): `src/arena_allocator.rs`
- [Slot-map API](https://github.com/chuck-ie/order-book/blob/main/src/slot_map/mod.rs): `src/slot_map/mod.rs`
- [Standard slot map](https://github.com/chuck-ie/order-book/blob/main/src/slot_map/standard.rs): `src/slot_map/standard.rs`
- [Optimized slot map](https://github.com/chuck-ie/order-book/blob/main/src/slot_map/optimized.rs): `src/slot_map/optimized.rs`
- [Chunked slots](https://github.com/chuck-ie/order-book/blob/main/src/slot_map/chunked.rs): `src/slot_map/chunked.rs`

### Channels

- [Channel API](https://github.com/chuck-ie/order-book/blob/main/src/channel/mod.rs): `src/channel/mod.rs`
- [Ring buffer](https://github.com/chuck-ie/order-book/blob/main/src/channel/ring_buffer.rs): `src/channel/ring_buffer.rs`
- [Producers](https://github.com/chuck-ie/order-book/blob/main/src/channel/producer.rs): `src/channel/producer.rs`
- [Consumers](https://github.com/chuck-ie/order-book/blob/main/src/channel/consumer.rs): `src/channel/consumer.rs`

### Benchmarking

- [Engine benchmarks](https://github.com/chuck-ie/order-book/blob/main/benches/shared/bench_engine.rs): `benches/shared/bench_engine.rs`
- [Result charts](https://github.com/chuck-ie/order-book/blob/main/benches/create_charts.rs): `benches/create_charts.rs`

### Other components

- **Library caller**

## Connections

- Library caller → Matcher API: submits commands
- Matcher API → V1 matcher: dispatches
- Matcher API → V2 matcher: dispatches
- Matcher API → V3 matcher: dispatches
- Matcher API → V4 matcher: dispatches
- Matcher API → V5 matcher: dispatches
- V1 matcher → V1 Vec book: updates and queries
- V2 matcher → V2 BTree book: updates and queries
- V3 matcher → V3 slot-map book: updates and queries
- V4 matcher → V4 arena book: updates and queries
- V5 matcher → V5 indexed book: updates and queries
- V4 matcher → Arena allocator: allocates and accesses
- V5 matcher → Arena allocator: allocates and accesses
- V4 arena book → Chunked slots: stores orders
- V5 indexed book → Chunked slots: stores orders
- Arena matcher API → Arena allocator: accepts arena
- Slot-map API → Standard slot map: defines implementations
- Slot-map API → Optimized slot map: defines implementations
- Slot-map API → Chunked slots: defines implementations
- Channel API → Ring buffer: constructs
- Channel API → Producers: exposes
- Channel API → Consumers: exposes
- Producers → Ring buffer: writes items
- Consumers → Ring buffer: reads items
- Engine benchmarks → Matcher API: benchmarks engines
- Engine benchmarks → Arena matcher API: benchmarks arena engines
- Result charts → Engine benchmarks: visualizes results