# woqwoq/bitcask architecture

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

- Interactive diagram: https://gitdiagram.com/woqwoq/bitcask
- Repository: https://github.com/woqwoq/bitcask

## Overview

Bitcask is an embedded, append-only key-value store. Its public database interface opens an instance and exposes reads, writes, removals, key enumeration, syncing, and merging; the sample CLI exercises open and repeated writes. Datafiles hold records, while the key directory and hint files support lookup and recovery. The engine is the central orchestration layer. The README is empty, and sampled engine excerpts are partial, so some likely runtime links are shown as unverified rather than asserted.

Main entry points: [`src/engine.rs`](https://github.com/woqwoq/bitcask/blob/master/src/engine.rs) (Bitcask engine), [`src/record.rs`](https://github.com/woqwoq/bitcask/blob/master/src/record.rs) (Record encoding), [`src/keydir.rs`](https://github.com/woqwoq/bitcask/blob/master/src/keydir.rs) (Key directory), [`src/main.rs`](https://github.com/woqwoq/bitcask/blob/master/src/main.rs) (Sample CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and entrypoints"]
  node_cli["Sample CLI<br/>[main.rs]"]
  node_database_api["Database API<br/>[db.rs]"]
end

subgraph group_engine["Database engine"]
  node_instance["Bitcask engine<br/>[engine.rs]"]
  node_options["Engine options<br/>[options.rs]"]
  node_errors["Error types<br/>[error.rs]"]
end

subgraph group_storage["Storage components"]
  node_records["Record encoding<br/>[record.rs]"]
  node_datafiles[("Datafiles<br/>[datafile.rs]")]
  node_keydir["Key directory<br/>[keydir.rs]"]
  node_hintfiles["Hint files<br/>[hint.rs]"]
end

node_caller(("Database caller"))

node_caller -.->|"uses"| node_database_api
node_caller -.->|"runs"| node_cli
node_cli -->|"opens and writes"| node_instance
node_database_api -->|"opens"| node_instance
node_instance -->|"configures from"| node_options
node_instance -->|"uses"| node_records
node_instance -->|"uses"| node_hintfiles
node_instance -.->|"uses"| node_datafiles
node_instance -.->|"indexes through"| node_keydir
node_datafiles -->|"replays into"| node_keydir
node_hintfiles -->|"loads into"| node_keydir
node_records -->|"uses sizes"| node_options
node_records -->|"reports"| node_errors

click node_cli "https://github.com/woqwoq/bitcask/blob/master/src/main.rs"
click node_database_api "https://github.com/woqwoq/bitcask/blob/master/src/db.rs"
click node_instance "https://github.com/woqwoq/bitcask/blob/master/src/engine.rs"
click node_options "https://github.com/woqwoq/bitcask/blob/master/src/options.rs"
click node_errors "https://github.com/woqwoq/bitcask/blob/master/src/error.rs"
click node_records "https://github.com/woqwoq/bitcask/blob/master/src/record.rs"
click node_datafiles "https://github.com/woqwoq/bitcask/blob/master/src/datafile.rs"
click node_keydir "https://github.com/woqwoq/bitcask/blob/master/src/keydir.rs"
click node_hintfiles "https://github.com/woqwoq/bitcask/blob/master/src/hint.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_cli,node_database_api toneBlue
class node_instance,node_options,node_errors,node_caller toneAmber
class node_records,node_datafiles,node_keydir,node_hintfiles toneMint
```

## Components

### API and entrypoints

- [Sample CLI](https://github.com/woqwoq/bitcask/blob/master/src/main.rs): `src/main.rs`
- [Database API](https://github.com/woqwoq/bitcask/blob/master/src/db.rs): `src/db.rs`

### Database engine

- [Bitcask engine](https://github.com/woqwoq/bitcask/blob/master/src/engine.rs): `src/engine.rs`
- [Engine options](https://github.com/woqwoq/bitcask/blob/master/src/options.rs): `src/options.rs`
- [Error types](https://github.com/woqwoq/bitcask/blob/master/src/error.rs): `src/error.rs`

### Storage components

- [Record encoding](https://github.com/woqwoq/bitcask/blob/master/src/record.rs): `src/record.rs`
- [Datafiles](https://github.com/woqwoq/bitcask/blob/master/src/datafile.rs): `src/datafile.rs`
- [Key directory](https://github.com/woqwoq/bitcask/blob/master/src/keydir.rs): `src/keydir.rs`
- [Hint files](https://github.com/woqwoq/bitcask/blob/master/src/hint.rs): `src/hint.rs`

### Other components

- **Database caller**

## Connections

- Database caller → Database API: uses
- Database caller → Sample CLI: runs
- Sample CLI → Bitcask engine: opens and writes (evidence: `src/main.rs`)
- Database API → Bitcask engine: opens (evidence: `src/db.rs`)
- Bitcask engine → Engine options: configures from (evidence: `src/engine.rs`)
- Bitcask engine → Record encoding: uses (evidence: `src/engine.rs`)
- Bitcask engine → Hint files: uses (evidence: `src/engine.rs`)
- Bitcask engine → Datafiles: uses
- Bitcask engine → Key directory: indexes through
- Datafiles → Key directory: replays into (evidence: `src/datafile.rs`)
- Hint files → Key directory: loads into (evidence: `src/hint.rs`)
- Record encoding → Engine options: uses sizes (evidence: `src/record.rs`)
- Record encoding → Error types: reports (evidence: `src/record.rs`)
