# scadoshi/chickadee architecture

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

- Interactive diagram: https://gitdiagram.com/scadoshi/chickadee
- Repository: https://github.com/scadoshi/chickadee

## Overview

Chickadee is a Rust log-structured key-value store, exposed through an interactive CLI and a concurrent TCP server. Both accept the same commands through a shared runner: parse and execute set/get/delete operations against the Log, which maintains a WAL and memtable and reads or flushes immutable SSTables. The documented storage lifecycle also includes corruption recovery, bloom-filter-assisted lookup, and periodic compaction. The graph uses README and indexed source references for some links; unsampled implementation details are not asserted beyond those references.

Main entry points: [`src/lib/log/mod.rs`](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/mod.rs) (Log engine), [`src/lib/log/sstable/mod.rs`](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/sstable/mod.rs) (SSTable reader), [`src/lib/log/command.rs`](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/command.rs) (Command parsing), [`src/lib/log/memtable.rs`](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/memtable.rs) (Memtable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI entry<br/>[cli.rs]"]
  node_server["TCP server<br/>[server.rs]"]
  node_runner["Command runner<br/>[run.rs]"]
  node_tui["Terminal help<br/>[tui.rs]"]
end

subgraph group_commands["Command handling"]
  node_command["Command parsing<br/>[command.rs]"]
  node_entry["Log entries<br/>[entry.rs]"]
end

subgraph group_engine["Storage engine"]
  node_log["Log engine<br/>[mod.rs]"]
  node_memtable[("Memtable<br/>[memtable.rs]")]
  node_sstable[("SSTable reader<br/>[mod.rs]")]
  node_compaction["SSTable compaction<br/>[compact.rs]"]
  node_bloom["Bloom filter<br/>[bloom_filter.rs]"]
end

subgraph group_persistence["Persistence internals"]
  node_wal[("WAL file<br/>[mod.rs]")]
  node_header["Record framing"]
end

node_cli_user(("CLI user"))
node_tcp_client(("TCP client"))

node_cli_user -->|"uses"| node_cli
node_cli -->|"starts"| node_runner
node_tcp_client -->|"connects"| node_server
node_server -->|"serves through"| node_runner
node_runner -->|"parses and executes"| node_command
node_command -->|"executes operations"| node_log
node_command -->|"creates entries"| node_entry
node_command -->|"shows help"| node_tui
node_log -->|"updates and queries"| node_memtable
node_log -->|"reads tables"| node_sstable
node_log -->|"appends and syncs"| node_wal
node_log -->|"writes records"| node_header
node_memtable -->|"reads and writes records"| node_header
node_memtable -->|"flushes entries"| node_sstable
node_sstable -->|"checks membership"| node_bloom
node_sstable -->|"reads records"| node_header
node_log -->|"compacts periodically"| node_compaction
node_compaction -->|"merges tables"| node_sstable
node_compaction -->|"buffers output"| node_memtable

click node_cli "https://github.com/scadoshi/chickadee/blob/main/src/bin/cli.rs"
click node_server "https://github.com/scadoshi/chickadee/blob/main/src/bin/server.rs"
click node_runner "https://github.com/scadoshi/chickadee/blob/main/src/lib/run.rs"
click node_tui "https://github.com/scadoshi/chickadee/blob/main/src/lib/tui.rs"
click node_command "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/command.rs"
click node_entry "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/entry.rs"
click node_log "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/mod.rs"
click node_memtable "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/memtable.rs"
click node_sstable "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/sstable/mod.rs"
click node_compaction "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/sstable/compact.rs"
click node_bloom "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/sstable/bloom_filter.rs"
click node_wal "https://github.com/scadoshi/chickadee/blob/main/src/lib/log/mod.rs"
click node_header "https://github.com/scadoshi/chickadee/tree/main/src/lib/log/header"

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_server,node_runner,node_tui,node_cli_user,node_tcp_client toneBlue
class node_command,node_entry toneAmber
class node_log,node_memtable,node_sstable,node_compaction,node_bloom toneMint
class node_wal,node_header toneRose
```

## Components

### User interfaces

- [CLI entry](https://github.com/scadoshi/chickadee/blob/main/src/bin/cli.rs): `src/bin/cli.rs`
- [TCP server](https://github.com/scadoshi/chickadee/blob/main/src/bin/server.rs): `src/bin/server.rs`
- [Command runner](https://github.com/scadoshi/chickadee/blob/main/src/lib/run.rs): `src/lib/run.rs`
- [Terminal help](https://github.com/scadoshi/chickadee/blob/main/src/lib/tui.rs): `src/lib/tui.rs`

### Command handling

- [Command parsing](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/command.rs): `src/lib/log/command.rs`
- [Log entries](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/entry.rs): `src/lib/log/entry.rs`

### Storage engine

- [Log engine](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/mod.rs): `src/lib/log/mod.rs`
- [Memtable](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/memtable.rs): `src/lib/log/memtable.rs`
- [SSTable reader](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/sstable/mod.rs): `src/lib/log/sstable/mod.rs`
- [SSTable compaction](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/sstable/compact.rs): `src/lib/log/sstable/compact.rs`
- [Bloom filter](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/sstable/bloom_filter.rs): `src/lib/log/sstable/bloom_filter.rs`

### Persistence internals

- [WAL file](https://github.com/scadoshi/chickadee/blob/main/src/lib/log/mod.rs): `src/lib/log/mod.rs`
- [Record framing](https://github.com/scadoshi/chickadee/tree/main/src/lib/log/header): `src/lib/log/header`

### Other components

- **CLI user**
- **TCP client**

## Connections

- CLI user → CLI entry: uses (evidence: `README.md`)
- CLI entry → Command runner: starts (evidence: `README.md`)
- TCP client → TCP server: connects (evidence: `README.md`)
- TCP server → Command runner: serves through (evidence: `README.md`)
- Command runner → Command parsing: parses and executes (evidence: `src/lib/run.rs`)
- Command parsing → Log engine: executes operations (evidence: `src/lib/log/command.rs`)
- Command parsing → Log entries: creates entries (evidence: `src/lib/log/command.rs`)
- Command parsing → Terminal help: shows help (evidence: `src/lib/log/command.rs`)
- Log engine → Memtable: updates and queries (evidence: `src/lib/log/mod.rs`)
- Log engine → SSTable reader: reads tables (evidence: `src/lib/log/mod.rs`)
- Log engine → WAL file: appends and syncs (evidence: `src/lib/log/mod.rs`)
- Log engine → Record framing: writes records (evidence: `src/lib/log/mod.rs`)
- Memtable → Record framing: reads and writes records (evidence: `src/lib/log/memtable.rs`)
- Memtable → SSTable reader: flushes entries (evidence: `README.md`)
- SSTable reader → Bloom filter: checks membership (evidence: `src/lib/log/sstable/mod.rs`)
- SSTable reader → Record framing: reads records (evidence: `src/lib/log/sstable/mod.rs`)
- Log engine → SSTable compaction: compacts periodically (evidence: `README.md`)
- SSTable compaction → SSTable reader: merges tables (evidence: `src/lib/log/sstable/compact.rs`)
- SSTable compaction → Memtable: buffers output (evidence: `src/lib/log/sstable/compact.rs`)
