# sereinsos/tiny-lsm architecture

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

- Interactive diagram: https://gitdiagram.com/sereinsos/tiny-lsm
- Repository: https://github.com/sereinsos/tiny-lsm

## Overview

Tiny-LSM is a C++ key-value database built around an LSM-tree, with a partly Redis-compatible server and Python SDK. The main workflow accepts library or Redis commands, applies them through the engine, and serves reads from memory or sorted-table files; writes are buffered and later flushed and compacted. Transactions/MVCC, WAL recovery, and optional WiscKey value separation extend that path. The map preserves documented Redis command families and storage layers; some subsystem links are omitted or dashed where sampled source does not establish the runtime call.

Main entry points: [`src/lsm/engine.cpp`](https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/engine.cpp) (LSM Engine), [`src/sst/sst.cpp`](https://github.com/sereinsos/tiny-lsm/blob/master/src/sst/sst.cpp) (SSTables), [`src/memtable/memtable.cpp`](https://github.com/sereinsos/tiny-lsm/blob/master/src/memtable/memtable.cpp) (MemTable), [`src/vlog/vlog.cpp`](https://github.com/sereinsos/tiny-lsm/blob/master/src/vlog/vlog.cpp) (Value Log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client Access"]
  node_library["C++ API<br/>[engine.h]"]
  node_redis_server["RESP Server<br/>[server.cpp]"]
  node_command_handler["Command Handler<br/>[handler.cpp]"]
  node_redis_wrapper["Redis Commands<br/>[redis_wrapper.cpp]"]
  node_python_sdk["Python SDK<br/>[lsm_pybind.cpp]"]
end

subgraph group_engine["LSM Engine"]
  node_lsm_engine["LSM Engine<br/>[engine.cpp]"]
  node_transactions["MVCC Transactions<br/>[transation.cpp]"]
  node_memtable["MemTable<br/>[memtable.cpp]"]
  node_skiplist["Skip List<br/>[skipList.cpp]"]
  node_merge_iterators["Merge Iterators"]
  node_level_iterator["Level Iterator<br/>[level_iterator.cpp]"]
end

subgraph group_storage["Storage Format"]
  node_sst[("SSTables<br/>[sst.cpp]")]
  node_block["Data Blocks<br/>[block.cpp]"]
  node_block_cache["Block Cache<br/>[block_cache.cpp]"]
  node_bloom_filter["Bloom Filter<br/>[bloom_filter.cpp]"]
  node_vlog[("Value Log<br/>[vlog.cpp]")]
end

subgraph group_durability["Durability &amp; Config"]
  node_wal[("Write-Ahead Log<br/>[wal.cpp]")]
  node_file_io["File I/O<br/>[files.cpp]"]
  node_config["TOML Config<br/>[config.cpp]"]
end

node_redis_client(("Redis Client"))

node_redis_client -->|"sends RESP"| node_redis_server
node_redis_server -->|"dispatches commands"| node_command_handler
node_command_handler -->|"invokes commands"| node_redis_wrapper
node_redis_wrapper -->|"uses database"| node_lsm_engine
node_library -->|"calls API"| node_lsm_engine
node_python_sdk -->|"binds API"| node_lsm_engine
node_lsm_engine -->|"checks reads"| node_memtable
node_lsm_engine -->|"queries SSTs"| node_sst
node_memtable -->|"stores entries"| node_skiplist
node_memtable -->|"builds on flush"| node_sst
node_lsm_engine -.->|"manages transactions"| node_transactions
node_lsm_engine -.->|"merges ranges"| node_merge_iterators
node_lsm_engine -.->|"exposes iteration"| node_level_iterator
node_sst -->|"encodes blocks"| node_block
node_sst -->|"uses cache"| node_block_cache
node_sst -->|"filters lookups"| node_bloom_filter
node_sst -->|"resolves values"| node_vlog
node_lsm_engine -->|"recreates log"| node_vlog
node_transactions -->|"uses WAL"| node_wal
node_wal -->|"persists records"| node_file_io
node_vlog -->|"reads and appends"| node_file_io
node_sst -->|"reads and writes"| node_file_io
node_lsm_engine -->|"reads settings"| node_config
node_memtable -->|"checks size limit"| node_config

click node_library "https://github.com/sereinsos/tiny-lsm/blob/master/include/lsm/engine.h"
click node_redis_server "https://github.com/sereinsos/tiny-lsm/blob/master/server/src/server.cpp"
click node_command_handler "https://github.com/sereinsos/tiny-lsm/blob/master/server/src/handler.cpp"
click node_redis_wrapper "https://github.com/sereinsos/tiny-lsm/blob/master/src/redis_wrapper/redis_wrapper.cpp"
click node_python_sdk "https://github.com/sereinsos/tiny-lsm/blob/master/sdk/lsm_pybind.cpp"
click node_lsm_engine "https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/engine.cpp"
click node_transactions "https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/transation.cpp"
click node_memtable "https://github.com/sereinsos/tiny-lsm/blob/master/src/memtable/memtable.cpp"
click node_skiplist "https://github.com/sereinsos/tiny-lsm/blob/master/src/skiplist/skipList.cpp"
click node_merge_iterators "https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/two_merge_iterator.cpp"
click node_level_iterator "https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/level_iterator.cpp"
click node_sst "https://github.com/sereinsos/tiny-lsm/blob/master/src/sst/sst.cpp"
click node_block "https://github.com/sereinsos/tiny-lsm/blob/master/src/block/block.cpp"
click node_block_cache "https://github.com/sereinsos/tiny-lsm/blob/master/src/block/block_cache.cpp"
click node_bloom_filter "https://github.com/sereinsos/tiny-lsm/blob/master/src/utils/bloom_filter.cpp"
click node_vlog "https://github.com/sereinsos/tiny-lsm/blob/master/src/vlog/vlog.cpp"
click node_wal "https://github.com/sereinsos/tiny-lsm/blob/master/src/wal/wal.cpp"
click node_file_io "https://github.com/sereinsos/tiny-lsm/blob/master/src/utils/files.cpp"
click node_config "https://github.com/sereinsos/tiny-lsm/blob/master/src/config/config.cpp"

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_library,node_redis_server,node_command_handler,node_redis_wrapper,node_python_sdk toneBlue
class node_lsm_engine,node_transactions,node_memtable,node_skiplist,node_merge_iterators,node_level_iterator,node_redis_client toneAmber
class node_sst,node_block,node_block_cache,node_bloom_filter,node_vlog toneMint
class node_wal,node_file_io,node_config toneRose
```

## Components

### Client Access

- [C++ API](https://github.com/sereinsos/tiny-lsm/blob/master/include/lsm/engine.h): `include/lsm/engine.h`
- [RESP Server](https://github.com/sereinsos/tiny-lsm/blob/master/server/src/server.cpp): `server/src/server.cpp`
- [Command Handler](https://github.com/sereinsos/tiny-lsm/blob/master/server/src/handler.cpp): `server/src/handler.cpp`
- [Redis Commands](https://github.com/sereinsos/tiny-lsm/blob/master/src/redis_wrapper/redis_wrapper.cpp): `src/redis_wrapper/redis_wrapper.cpp`
- [Python SDK](https://github.com/sereinsos/tiny-lsm/blob/master/sdk/lsm_pybind.cpp): `sdk/lsm_pybind.cpp`

### LSM Engine

- [LSM Engine](https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/engine.cpp): `src/lsm/engine.cpp`
- [MVCC Transactions](https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/transation.cpp): `src/lsm/transation.cpp`
- [MemTable](https://github.com/sereinsos/tiny-lsm/blob/master/src/memtable/memtable.cpp): `src/memtable/memtable.cpp`
- [Skip List](https://github.com/sereinsos/tiny-lsm/blob/master/src/skiplist/skipList.cpp): `src/skiplist/skipList.cpp`
- [Merge Iterators](https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/two_merge_iterator.cpp): `src/lsm/two_merge_iterator.cpp`
- [Level Iterator](https://github.com/sereinsos/tiny-lsm/blob/master/src/lsm/level_iterator.cpp): `src/lsm/level_iterator.cpp`

### Storage Format

- [SSTables](https://github.com/sereinsos/tiny-lsm/blob/master/src/sst/sst.cpp): `src/sst/sst.cpp`
- [Data Blocks](https://github.com/sereinsos/tiny-lsm/blob/master/src/block/block.cpp): `src/block/block.cpp`
- [Block Cache](https://github.com/sereinsos/tiny-lsm/blob/master/src/block/block_cache.cpp): `src/block/block_cache.cpp`
- [Bloom Filter](https://github.com/sereinsos/tiny-lsm/blob/master/src/utils/bloom_filter.cpp): `src/utils/bloom_filter.cpp`
- [Value Log](https://github.com/sereinsos/tiny-lsm/blob/master/src/vlog/vlog.cpp): `src/vlog/vlog.cpp`

### Durability & Config

- [Write-Ahead Log](https://github.com/sereinsos/tiny-lsm/blob/master/src/wal/wal.cpp): `src/wal/wal.cpp`
- [File I/O](https://github.com/sereinsos/tiny-lsm/blob/master/src/utils/files.cpp): `src/utils/files.cpp`
- [TOML Config](https://github.com/sereinsos/tiny-lsm/blob/master/src/config/config.cpp): `src/config/config.cpp`

### Other components

- **Redis Client**

## Connections

- Redis Client → RESP Server: sends RESP
- RESP Server → Command Handler: dispatches commands (evidence: `server/src/server.cpp`)
- Command Handler → Redis Commands: invokes commands (evidence: `server/src/handler.cpp`)
- Redis Commands → LSM Engine: uses database
- C++ API → LSM Engine: calls API (evidence: `src/lsm/engine.cpp`)
- Python SDK → LSM Engine: binds API (evidence: `sdk/lsm_pybind.cpp`)
- LSM Engine → MemTable: checks reads (evidence: `src/lsm/engine.cpp`)
- LSM Engine → SSTables: queries SSTs (evidence: `src/lsm/engine.cpp`)
- MemTable → Skip List: stores entries (evidence: `src/memtable/memtable.cpp`)
- MemTable → SSTables: builds on flush (evidence: `src/memtable/memtable.cpp`)
- LSM Engine → MVCC Transactions: manages transactions
- LSM Engine → Merge Iterators: merges ranges
- LSM Engine → Level Iterator: exposes iteration
- SSTables → Data Blocks: encodes blocks
- SSTables → Block Cache: uses cache
- SSTables → Bloom Filter: filters lookups
- SSTables → Value Log: resolves values
- LSM Engine → Value Log: recreates log (evidence: `src/lsm/engine.cpp`)
- MVCC Transactions → Write-Ahead Log: uses WAL
- Write-Ahead Log → File I/O: persists records
- Value Log → File I/O: reads and appends
- SSTables → File I/O: reads and writes
- LSM Engine → TOML Config: reads settings (evidence: `src/lsm/engine.cpp`)
- MemTable → TOML Config: checks size limit (evidence: `src/memtable/memtable.cpp`)
