# admin-ac-hub/kv_mem architecture

> Architecture diagram of the GitHub repository admin-ac-hub/kv_mem, 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/admin-ac-hub/kv_mem
- Repository: https://github.com/admin-ac-hub/kv_mem

## Overview

Mini LSM-KV is a single-machine persistent key-value engine with vector storage and ANN search. Applications submit puts, deletes, or atomic batches through DB; writes are logged before entering the MemTable, then flushed and compacted into SSTables. Reads use sequence-aware MVCC across memory and disk, while startup replays the Manifest and live WALs. Vector values share this storage lifecycle and support exact search and HNSW search. The graph follows documented architecture and sampled source; several subsystem links are documented capabilities whose implementation was not sampled.

Main entry points: [`src/db.cc`](https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc) (DB Engine), [`src/sstable.cpp`](https://github.com/admin-ac-hub/kv_mem/blob/main/src/sstable.cpp) (SSTable), [`src/manifest.cpp`](https://github.com/admin-ac-hub/kv_mem/blob/main/src/manifest.cpp) (Manifest), [`src/hnsw_index.cc`](https://github.com/admin-ac-hub/kv_mem/blob/main/src/hnsw_index.cc) (HNSW Index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Database API"]
  node_db["DB Engine<br/>[db.cc]"]
  node_batch["WriteBatch<br/>[write_batch.cc]"]
  node_mvcc["Snapshots MVCC<br/>[db.cc]"]
end

subgraph group_write["Write And Recovery"]
  node_wal["Write-Ahead Log<br/>[wal.cc]"]
  node_memtable["MemTable<br/>[memtable.cc]"]
  node_maintenance["Flush Compaction<br/>[db.cc]"]
  node_manifest["Manifest<br/>[manifest.cpp]"]
  node_recovery["Recovery<br/>[db.cc]"]
end

subgraph group_read["Read And Storage"]
  node_sstable[("SSTable<br/>[sstable.cpp]")]
  node_bloom["Bloom Filter<br/>[bloom_filter.cc]"]
  node_cache["Block Cache<br/>[block_cache.cc]"]
  node_iterator["Merge Iterator"]
end

subgraph group_vector["Vector Search"]
  node_vector_codec["Vector Encoding<br/>[vector_value.cc]"]
  node_exact["Exact Top-K<br/>[db.cc]"]
  node_hnsw[("HNSW Index<br/>[hnsw_index.cc]")]
end

node_client(("Application"))

node_client -->|"calls"| node_db
node_db -->|"applies"| node_batch
node_db -->|"appends and syncs"| node_wal
node_db -->|"updates"| node_memtable
node_db -->|"schedules"| node_maintenance
node_maintenance -->|"flushes and merges"| node_sstable
node_maintenance -->|"publishes version"| node_manifest
node_db -->|"uses sequence"| node_mvcc
node_db -->|"reads"| node_memtable
node_db -->|"reads"| node_sstable
node_sstable -->|"checks keys"| node_bloom
node_sstable -->|"gets and fills blocks"| node_cache
node_db -->|"creates scan"| node_iterator
node_db -->|"replays on open"| node_manifest
node_recovery -->|"loads version"| node_manifest
node_recovery -->|"opens live files"| node_sstable
node_recovery -->|"replays live logs"| node_wal
node_db -->|"encodes and decodes"| node_vector_codec
node_db -->|"runs baseline search"| node_exact
node_db -->|"searches and updates"| node_hnsw
node_maintenance -->|"builds index files"| node_hnsw
node_recovery -->|"loads index files"| node_hnsw

click node_db "https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc"
click node_batch "https://github.com/admin-ac-hub/kv_mem/blob/main/src/write_batch.cc"
click node_mvcc "https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc"
click node_wal "https://github.com/admin-ac-hub/kv_mem/blob/main/src/wal.cc"
click node_memtable "https://github.com/admin-ac-hub/kv_mem/blob/main/src/memtable.cc"
click node_maintenance "https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc"
click node_sstable "https://github.com/admin-ac-hub/kv_mem/blob/main/src/sstable.cpp"
click node_manifest "https://github.com/admin-ac-hub/kv_mem/blob/main/src/manifest.cpp"
click node_recovery "https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc"
click node_bloom "https://github.com/admin-ac-hub/kv_mem/blob/main/src/bloom_filter.cc"
click node_cache "https://github.com/admin-ac-hub/kv_mem/blob/main/src/block_cache.cc"
click node_iterator "https://github.com/admin-ac-hub/kv_mem/blob/main/include/internal_iterator.h"
click node_vector_codec "https://github.com/admin-ac-hub/kv_mem/blob/main/src/vector_value.cc"
click node_exact "https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc"
click node_hnsw "https://github.com/admin-ac-hub/kv_mem/blob/main/src/hnsw_index.cc"

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_batch,node_mvcc toneBlue
class node_wal,node_memtable,node_maintenance,node_manifest,node_recovery toneAmber
class node_sstable,node_bloom,node_cache,node_iterator toneMint
class node_vector_codec,node_exact,node_hnsw toneRose
class node_client toneIndigo
```

## Components

### Database API

- [DB Engine](https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc): `src/db.cc`
- [WriteBatch](https://github.com/admin-ac-hub/kv_mem/blob/main/src/write_batch.cc): `src/write_batch.cc`
- [Snapshots MVCC](https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc): `src/db.cc`

### Write And Recovery

- [Write-Ahead Log](https://github.com/admin-ac-hub/kv_mem/blob/main/src/wal.cc): `src/wal.cc`
- [MemTable](https://github.com/admin-ac-hub/kv_mem/blob/main/src/memtable.cc): `src/memtable.cc`
- [Flush Compaction](https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc): `src/db.cc`
- [Manifest](https://github.com/admin-ac-hub/kv_mem/blob/main/src/manifest.cpp): `src/manifest.cpp`
- [Recovery](https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc): `src/db.cc`

### Read And Storage

- [SSTable](https://github.com/admin-ac-hub/kv_mem/blob/main/src/sstable.cpp): `src/sstable.cpp`
- [Bloom Filter](https://github.com/admin-ac-hub/kv_mem/blob/main/src/bloom_filter.cc): `src/bloom_filter.cc`
- [Block Cache](https://github.com/admin-ac-hub/kv_mem/blob/main/src/block_cache.cc): `src/block_cache.cc`
- [Merge Iterator](https://github.com/admin-ac-hub/kv_mem/blob/main/include/internal_iterator.h): `include/internal_iterator.h`

### Vector Search

- [Vector Encoding](https://github.com/admin-ac-hub/kv_mem/blob/main/src/vector_value.cc): `src/vector_value.cc`
- [Exact Top-K](https://github.com/admin-ac-hub/kv_mem/blob/main/src/db.cc): `src/db.cc`
- [HNSW Index](https://github.com/admin-ac-hub/kv_mem/blob/main/src/hnsw_index.cc): `src/hnsw_index.cc`

### Other components

- **Application**

## Connections

- Application → DB Engine: calls
- DB Engine → WriteBatch: applies
- DB Engine → Write-Ahead Log: appends and syncs
- DB Engine → MemTable: updates
- DB Engine → Flush Compaction: schedules
- Flush Compaction → SSTable: flushes and merges
- Flush Compaction → Manifest: publishes version
- DB Engine → Snapshots MVCC: uses sequence
- DB Engine → MemTable: reads
- DB Engine → SSTable: reads
- SSTable → Bloom Filter: checks keys
- SSTable → Block Cache: gets and fills blocks
- DB Engine → Merge Iterator: creates scan
- DB Engine → Manifest: replays on open
- Recovery → Manifest: loads version
- Recovery → SSTable: opens live files
- Recovery → Write-Ahead Log: replays live logs
- DB Engine → Vector Encoding: encodes and decodes
- DB Engine → Exact Top-K: runs baseline search
- DB Engine → HNSW Index: searches and updates
- Flush Compaction → HNSW Index: builds index files
- Recovery → HNSW Index: loads index files