# kosumic/b-epsilon-tree architecture

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

- Interactive diagram: https://gitdiagram.com/kosumic/b-epsilon-tree
- Repository: https://github.com/kosumic/b-epsilon-tree

## Overview

This Rust library implements a persistent Bε-tree key/value store. A caller inserts or retrieves byte-string keys and values through the tree API: inserts become messages routed through internal nodes to leaves, while reads traverse the tree. The tree coordinates copy-on-write pages and metadata with a node cache; the cache uses a page pager for disk I/O. Serialization defines the on-disk representation. The WAL is present in metadata but appears skeletal in the sampled code. Relationships below are limited to the README and shown source; other tree operations were not fully sampled.

Main entry points: [`src/betree.rs`](https://github.com/kosumic/b-epsilon-tree/blob/master/src/betree.rs) (Bε-tree API), [`src/pool.rs`](https://github.com/kosumic/b-epsilon-tree/blob/master/src/pool.rs) (Node cache), [`src/superblock.rs`](https://github.com/kosumic/b-epsilon-tree/blob/master/src/superblock.rs) (Tree metadata), [`src/node.rs`](https://github.com/kosumic/b-epsilon-tree/blob/master/src/node.rs) (Internal nodes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tree["Tree engine"]
  node_betree["Bε-tree API<br/>[betree.rs]"]
  node_internal["Internal nodes<br/>[node.rs]"]
  node_leaves["Leaf nodes<br/>[node.rs]"]
  node_args["Configuration arguments<br/>[args.rs]"]
end

subgraph group_storage["Page storage"]
  node_cache["Node cache<br/>[pool.rs]"]
  node_pager["Page pager<br/>[pager.rs]"]
  node_superblock[("Tree metadata<br/>[superblock.rs]")]
  node_allocator["Page allocator<br/>[allocator.rs]"]
  node_wal["WAL metadata<br/>[wal.rs]"]
end

subgraph group_format["On-disk format"]
  node_page["Fixed-size pages<br/>[page.rs]"]
  node_serialization["Serialization types<br/>[types.rs]"]
end

node_caller(("Library caller"))
node_disk[("Storage file")]

node_caller -->|"calls API"| node_betree
node_betree -->|"routes messages"| node_internal
node_betree -->|"applies messages"| node_leaves
node_betree -->|"loads nodes"| node_cache
node_betree -->|"allocates pages"| node_superblock
node_betree -->|"imports allocator"| node_allocator
node_internal -->|"serializes nodes"| node_serialization
node_internal -->|"converts pages"| node_page
node_cache -->|"reads and writes"| node_pager
node_cache -->|"converts cached nodes"| node_page
node_cache -->|"caches nodes"| node_internal
node_pager -->|"reads and writes"| node_disk
node_pager -->|"transfers pages"| node_page
node_superblock -->|"owns allocator"| node_allocator
node_superblock -->|"stores WAL state"| node_wal
node_superblock -->|"serializes metadata page"| node_page
node_allocator -->|"serializes counter"| node_serialization

click node_betree "https://github.com/kosumic/b-epsilon-tree/blob/master/src/betree.rs"
click node_internal "https://github.com/kosumic/b-epsilon-tree/blob/master/src/node.rs"
click node_leaves "https://github.com/kosumic/b-epsilon-tree/blob/master/src/node.rs"
click node_cache "https://github.com/kosumic/b-epsilon-tree/blob/master/src/pool.rs"
click node_pager "https://github.com/kosumic/b-epsilon-tree/blob/master/src/pager.rs"
click node_superblock "https://github.com/kosumic/b-epsilon-tree/blob/master/src/superblock.rs"
click node_allocator "https://github.com/kosumic/b-epsilon-tree/blob/master/src/allocator.rs"
click node_wal "https://github.com/kosumic/b-epsilon-tree/blob/master/src/wal.rs"
click node_page "https://github.com/kosumic/b-epsilon-tree/blob/master/src/page.rs"
click node_serialization "https://github.com/kosumic/b-epsilon-tree/blob/master/src/types.rs"
click node_args "https://github.com/kosumic/b-epsilon-tree/blob/master/src/args.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_betree,node_internal,node_leaves,node_args toneBlue
class node_cache,node_pager,node_superblock,node_allocator,node_wal,node_disk toneAmber
class node_page,node_serialization toneMint
class node_caller toneIndigo
```

## Components

### Tree engine

- [Bε-tree API](https://github.com/kosumic/b-epsilon-tree/blob/master/src/betree.rs): `src/betree.rs`
- [Internal nodes](https://github.com/kosumic/b-epsilon-tree/blob/master/src/node.rs): `src/node.rs`
- [Leaf nodes](https://github.com/kosumic/b-epsilon-tree/blob/master/src/node.rs): `src/node.rs`
- [Configuration arguments](https://github.com/kosumic/b-epsilon-tree/blob/master/src/args.rs): `src/args.rs`

### Page storage

- [Node cache](https://github.com/kosumic/b-epsilon-tree/blob/master/src/pool.rs): `src/pool.rs`
- [Page pager](https://github.com/kosumic/b-epsilon-tree/blob/master/src/pager.rs): `src/pager.rs`
- [Tree metadata](https://github.com/kosumic/b-epsilon-tree/blob/master/src/superblock.rs): `src/superblock.rs`
- [Page allocator](https://github.com/kosumic/b-epsilon-tree/blob/master/src/allocator.rs): `src/allocator.rs`
- [WAL metadata](https://github.com/kosumic/b-epsilon-tree/blob/master/src/wal.rs): `src/wal.rs`

### On-disk format

- [Fixed-size pages](https://github.com/kosumic/b-epsilon-tree/blob/master/src/page.rs): `src/page.rs`
- [Serialization types](https://github.com/kosumic/b-epsilon-tree/blob/master/src/types.rs): `src/types.rs`

### Other components

- **Library caller**
- **Storage file**

## Connections

- Library caller → Bε-tree API: calls API (evidence: `README.md`)
- Bε-tree API → Internal nodes: routes messages (evidence: `src/betree.rs`)
- Bε-tree API → Leaf nodes: applies messages (evidence: `src/betree.rs`)
- Bε-tree API → Node cache: loads nodes (evidence: `src/betree.rs`)
- Bε-tree API → Tree metadata: allocates pages (evidence: `src/betree.rs`)
- Bε-tree API → Page allocator: imports allocator (evidence: `src/betree.rs`)
- Internal nodes → Serialization types: serializes nodes (evidence: `src/node.rs`)
- Internal nodes → Fixed-size pages: converts pages (evidence: `src/node.rs`)
- Node cache → Page pager: reads and writes (evidence: `src/pool.rs`)
- Node cache → Fixed-size pages: converts cached nodes (evidence: `src/pool.rs`)
- Node cache → Internal nodes: caches nodes (evidence: `src/pool.rs`)
- Page pager → Storage file: reads and writes (evidence: `src/pager.rs`)
- Page pager → Fixed-size pages: transfers pages (evidence: `src/pager.rs`)
- Tree metadata → Page allocator: owns allocator (evidence: `src/superblock.rs`)
- Tree metadata → WAL metadata: stores WAL state (evidence: `src/superblock.rs`)
- Tree metadata → Fixed-size pages: serializes metadata page (evidence: `src/superblock.rs`)
- Page allocator → Serialization types: serializes counter (evidence: `src/allocator.rs`)
