# mxdvf/orange architecture

> Architecture diagram of the GitHub repository mxdvf/orange, 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/mxdvf/orange
- Repository: https://github.com/mxdvf/orange

## Overview

Orange is a persistent, copy-on-write B-tree storage engine: callers insert, search, and delete byte keys and values, with writes committed in batches and reads served from the tree. The tree encodes nodes into fixed-size pages; page management provides mapped-file I/O, allocation, and durability, while the master page tracks the root and reusable pages. The README also documents crash-safe fsync, memory mapping, and group commit. Some B-tree and node-manager excerpts are partial, so the graph omits uncertain internal links.

Main entry points: [`btree/btree.go`](https://github.com/mxdvf/orange/blob/main/btree/btree.go) (Persistent B-Tree), [`engine/engine.go`](https://github.com/mxdvf/orange/blob/main/engine/engine.go) (Engine API), [`btree/btree_util.go`](https://github.com/mxdvf/orange/blob/main/btree/btree_util.go) (Tree Page Helpers), [`pagemanager/page_manager.go`](https://github.com/mxdvf/orange/blob/main/pagemanager/page_manager.go) (Page Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Commit"]
  node_engine["Engine API<br/>[engine.go]"]
  node_commit["Batch Commit<br/>[engine.go]"]
end

subgraph group_tree["B-Tree Operations"]
  node_btree["Persistent B-Tree<br/>[btree.go]"]
  node_treeutil["Tree Page Helpers<br/>[btree_util.go]"]
end

subgraph group_pages["Page Storage"]
  node_pages["Page Manager<br/>[page_manager.go]"]
  node_allocator["Platform Allocator"]
  node_mappedfile[("Mapped File<br/>[page_manager.go]")]
end

subgraph group_format["Node Format"]
  node_node["Node Encoding<br/>[node_manager.go]"]
end

node_caller(("Application"))

node_caller -->|"calls API"| node_engine
node_engine -->|"queues writes"| node_commit
node_engine -->|"searches"| node_btree
node_commit -->|"applies batch"| node_btree
node_commit -->|"syncs and publishes"| node_btree
node_btree -->|"loads and saves pages"| node_treeutil
node_btree -->|"reads and edits nodes"| node_node
node_treeutil -->|"decodes pages"| node_node
node_treeutil -->|"reads and writes"| node_pages
node_pages -->|"allocates pages"| node_allocator
node_pages -->|"maps and accesses"| node_mappedfile
node_allocator -->|"extends mapping"| node_mappedfile

click node_engine "https://github.com/mxdvf/orange/blob/main/engine/engine.go"
click node_commit "https://github.com/mxdvf/orange/blob/main/engine/engine.go"
click node_btree "https://github.com/mxdvf/orange/blob/main/btree/btree.go"
click node_treeutil "https://github.com/mxdvf/orange/blob/main/btree/btree_util.go"
click node_node "https://github.com/mxdvf/orange/blob/main/nodemanager/node_manager.go"
click node_pages "https://github.com/mxdvf/orange/blob/main/pagemanager/page_manager.go"
click node_allocator "https://github.com/mxdvf/orange/blob/main/pagemanager/page_manager_linux.go"
click node_mappedfile "https://github.com/mxdvf/orange/blob/main/pagemanager/page_manager.go"

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_engine,node_commit toneBlue
class node_btree,node_treeutil toneAmber
class node_pages,node_allocator,node_mappedfile toneMint
class node_node toneRose
class node_caller toneIndigo
```

## Components

### API and Commit

- [Engine API](https://github.com/mxdvf/orange/blob/main/engine/engine.go): `engine/engine.go`
- [Batch Commit](https://github.com/mxdvf/orange/blob/main/engine/engine.go): `engine/engine.go`

### B-Tree Operations

- [Persistent B-Tree](https://github.com/mxdvf/orange/blob/main/btree/btree.go): `btree/btree.go`
- [Tree Page Helpers](https://github.com/mxdvf/orange/blob/main/btree/btree_util.go): `btree/btree_util.go`

### Page Storage

- [Page Manager](https://github.com/mxdvf/orange/blob/main/pagemanager/page_manager.go): `pagemanager/page_manager.go`
- [Platform Allocator](https://github.com/mxdvf/orange/blob/main/pagemanager/page_manager_linux.go): `pagemanager/page_manager_linux.go`
- [Mapped File](https://github.com/mxdvf/orange/blob/main/pagemanager/page_manager.go): `pagemanager/page_manager.go`

### Node Format

- [Node Encoding](https://github.com/mxdvf/orange/blob/main/nodemanager/node_manager.go): `nodemanager/node_manager.go`

### Other components

- **Application**

## Connections

- Application → Engine API: calls API
- Engine API → Batch Commit: queues writes
- Engine API → Persistent B-Tree: searches
- Batch Commit → Persistent B-Tree: applies batch
- Batch Commit → Persistent B-Tree: syncs and publishes
- Persistent B-Tree → Tree Page Helpers: loads and saves pages
- Persistent B-Tree → Node Encoding: reads and edits nodes
- Tree Page Helpers → Node Encoding: decodes pages
- Tree Page Helpers → Page Manager: reads and writes
- Page Manager → Platform Allocator: allocates pages
- Page Manager → Mapped File: maps and accesses
- Platform Allocator → Mapped File: extends mapping