# saint-yellow/baradb architecture

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

- Interactive diagram: https://gitdiagram.com/saint-yellow/baradb
- Repository: https://github.com/saint-yellow/baradb

## Overview

baradb is a Bitcask-style key/value storage engine. Its core workflow appends encoded records to data files and indexes their positions; reads look up a position and fetch the record. Batch writes add transactional records, while startup rebuilds the index and merging compacts live records. The excerpts establish these core paths and the I/O/index implementations; batch, iterator, and some lifecycle wiring are represented only where the README or sampled code supports them.

Main entry points: [`db.go`](https://github.com/saint-yellow/baradb/blob/master/db.go) (DB engine), [`index/index.go`](https://github.com/saint-yellow/baradb/blob/master/index/index.go) (Index interface), [`data/data_file.go`](https://github.com/saint-yellow/baradb/blob/master/data/data_file.go) (Data files), [`io_handler/io_handler.go`](https://github.com/saint-yellow/baradb/blob/master/io_handler/io_handler.go) (File I/O)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["DB Engine"]
  node_db["DB engine<br/>[db.go]"]
  node_options["DB options<br/>[options.go]"]
end

subgraph group_storage["Log Storage"]
  node_datafile[("Data files<br/>[data_file.go]")]
  node_record["Log records<br/>[log_record.go]"]
  node_io["File I/O<br/>[io_handler.go]"]
  node_fileio["File handler<br/>[file_io.go]"]
  node_mmap["Mapped reads<br/>[mmap.go]"]
  node_position["Record position<br/>[log_record.go]"]
end

subgraph group_lookup["Indexing"]
  node_indexapi["Index interface<br/>[index.go]"]
  node_indexmem["Tree indexes<br/>[btree.go]"]
  node_indexdisk[("B+ tree index<br/>[bptree.go]")]
end

subgraph group_operations["DB Operations"]
  node_batch["Write batch<br/>[batch.go]"]
  node_iterator["DB iterator<br/>[iterator.go]"]
  node_stats["DB statistics<br/>[stat.go]"]
  node_merge["Log merge<br/>[mergence.go]"]
end

node_client(("DB client"))

node_client -->|"calls API"| node_db
node_db -->|"uses settings"| node_options
node_db -->|"encodes writes"| node_record
node_db -->|"appends records"| node_datafile
node_db -->|"updates index"| node_indexapi
node_db -->|"looks up key"| node_indexapi
node_indexapi -->|"selects tree"| node_indexmem
node_indexapi -->|"selects B+ tree"| node_indexdisk
node_indexmem -->|"stores positions"| node_position
node_indexdisk -->|"stores positions"| node_position
node_db -->|"resolves location"| node_position
node_db -->|"reads value"| node_datafile
node_datafile -->|"uses handler"| node_io
node_io -->|"opens file"| node_fileio
node_io -.->|"opens mapped file"| node_mmap
node_db -->|"loads files"| node_datafile
node_db -->|"rebuilds index"| node_indexapi
node_db -->|"creates batch"| node_batch
node_batch -->|"commits writes"| node_db
node_db -->|"iterates keys"| node_iterator
node_db -->|"reports state"| node_stats
node_client -->|"requests compaction"| node_merge
node_merge -->|"rewrites live records"| node_datafile
node_merge -->|"checks live positions"| node_indexapi

click node_db "https://github.com/saint-yellow/baradb/blob/master/db.go"
click node_options "https://github.com/saint-yellow/baradb/blob/master/options.go"
click node_batch "https://github.com/saint-yellow/baradb/blob/master/batch.go"
click node_iterator "https://github.com/saint-yellow/baradb/blob/master/iterator.go"
click node_stats "https://github.com/saint-yellow/baradb/blob/master/stat.go"
click node_merge "https://github.com/saint-yellow/baradb/blob/master/mergence.go"
click node_datafile "https://github.com/saint-yellow/baradb/blob/master/data/data_file.go"
click node_record "https://github.com/saint-yellow/baradb/blob/master/data/log_record.go"
click node_io "https://github.com/saint-yellow/baradb/blob/master/io_handler/io_handler.go"
click node_fileio "https://github.com/saint-yellow/baradb/blob/master/io_handler/file_io.go"
click node_mmap "https://github.com/saint-yellow/baradb/blob/master/io_handler/mmap.go"
click node_indexapi "https://github.com/saint-yellow/baradb/blob/master/index/index.go"
click node_indexmem "https://github.com/saint-yellow/baradb/blob/master/index/btree.go"
click node_indexdisk "https://github.com/saint-yellow/baradb/blob/master/index/bptree.go"
click node_position "https://github.com/saint-yellow/baradb/blob/master/data/log_record.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_db,node_options,node_client toneBlue
class node_datafile,node_record,node_io,node_fileio,node_mmap,node_position toneAmber
class node_indexapi,node_indexmem,node_indexdisk toneMint
class node_batch,node_iterator,node_stats,node_merge toneRose
```

## Components

### DB Engine

- [DB engine](https://github.com/saint-yellow/baradb/blob/master/db.go): `db.go`
- [DB options](https://github.com/saint-yellow/baradb/blob/master/options.go): `options.go`

### Log Storage

- [Data files](https://github.com/saint-yellow/baradb/blob/master/data/data_file.go): `data/data_file.go`
- [Log records](https://github.com/saint-yellow/baradb/blob/master/data/log_record.go): `data/log_record.go`
- [File I/O](https://github.com/saint-yellow/baradb/blob/master/io_handler/io_handler.go): `io_handler/io_handler.go`
- [File handler](https://github.com/saint-yellow/baradb/blob/master/io_handler/file_io.go): `io_handler/file_io.go`
- [Mapped reads](https://github.com/saint-yellow/baradb/blob/master/io_handler/mmap.go): `io_handler/mmap.go`
- [Record position](https://github.com/saint-yellow/baradb/blob/master/data/log_record.go): `data/log_record.go`

### Indexing

- [Index interface](https://github.com/saint-yellow/baradb/blob/master/index/index.go): `index/index.go`
- [Tree indexes](https://github.com/saint-yellow/baradb/blob/master/index/btree.go): `index/btree.go`
- [B+ tree index](https://github.com/saint-yellow/baradb/blob/master/index/bptree.go): `index/bptree.go`

### DB Operations

- [Write batch](https://github.com/saint-yellow/baradb/blob/master/batch.go): `batch.go`
- [DB iterator](https://github.com/saint-yellow/baradb/blob/master/iterator.go): `iterator.go`
- [DB statistics](https://github.com/saint-yellow/baradb/blob/master/stat.go): `stat.go`
- [Log merge](https://github.com/saint-yellow/baradb/blob/master/mergence.go): `mergence.go`

### Other components

- **DB client**

## Connections

- DB client → DB engine: calls API
- DB engine → DB options: uses settings
- DB engine → Log records: encodes writes
- DB engine → Data files: appends records
- DB engine → Index interface: updates index
- DB engine → Index interface: looks up key
- Index interface → Tree indexes: selects tree
- Index interface → B+ tree index: selects B+ tree
- Tree indexes → Record position: stores positions
- B+ tree index → Record position: stores positions
- DB engine → Record position: resolves location
- DB engine → Data files: reads value
- Data files → File I/O: uses handler
- File I/O → File handler: opens file
- File I/O → Mapped reads: opens mapped file
- DB engine → Data files: loads files
- DB engine → Index interface: rebuilds index
- DB engine → Write batch: creates batch
- Write batch → DB engine: commits writes
- DB engine → DB iterator: iterates keys
- DB engine → DB statistics: reports state
- DB client → Log merge: requests compaction
- Log merge → Data files: rewrites live records
- Log merge → Index interface: checks live positions