# benahmed-adam/zestdb architecture

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

- Interactive diagram: https://gitdiagram.com/benahmed-adam/zestdb
- Repository: https://github.com/benahmed-adam/zestdb

## Overview

ZestDB is a disk-persistent, sharded key-value database. Its main workflow is TCP client commands through session framing/authentication, command parsing and validation, hash-based shard dispatch, and durable indexed storage; bulk pattern operations fan out across shards. Separate documented capabilities include HTTP metrics, configuration control, WAL recovery, background flush/compaction, archiving, and logging. Edges reflect README statements or indexed source references; unsampled internals are represented at their exact source paths, and uncertain wiring is omitted.

Main entry points: [`src/ZestDB.cpp`](https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp) (Database facade), [`src/Shard.cpp`](https://github.com/benahmed-adam/zestdb/blob/main/src/Shard.cpp) (Shard engine), [`src/ShardManager.cpp`](https://github.com/benahmed-adam/zestdb/blob/main/src/ShardManager.cpp) (Shard routing), [`src/Server.cpp`](https://github.com/benahmed-adam/zestdb/blob/main/src/Server.cpp) (Session framing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client access"]
  node_session["Session framing<br/>[Server.cpp]"]
  node_tcp["TCP server<br/>[Server.cpp]"]
end

subgraph group_commands["Command and control"]
  node_db["Database facade<br/>[ZestDB.cpp]"]
  node_config["Config management<br/>[ZestDB.cpp]"]
end

subgraph group_sharding["Sharded execution"]
  node_shardmgr["Shard routing<br/>[ShardManager.cpp]"]
  node_bulk["Parallel bulk ops<br/>[ShardManager.cpp]"]
  node_shard["Shard engine<br/>[Shard.cpp]"]
  node_threadpool["Worker pool<br/>[ThreadPool.cpp]"]
end

subgraph group_storage["Durable storage"]
  node_index[("In-memory index<br/>[IndexManager.cpp]")]
  node_segments[("Segment storage<br/>[StorageManager.cpp]")]
  node_cache["LRU cache<br/>[LRUCache.cpp]"]
  node_wal[("Write-ahead log<br/>[WAL.cpp]")]
end

subgraph group_operations["Operations and observability"]
  node_monitor["Performance counters<br/>[PerfMonitoring.cpp]"]
  node_http["HTTP metrics<br/>[ZestDB.cpp]"]
  node_maintenance["Flush and compaction<br/>[Shard.cpp]"]
  node_archive["Database archiving<br/>[ZestDB.cpp]"]
  node_logger["Logging<br/>[Logger.cpp]"]
end

node_client(("TCP client"))

node_client -->|"sends commands"| node_tcp
node_tcp -->|"accepts sessions"| node_session
node_session -->|"dispatches commands"| node_db
node_db -->|"routes operations"| node_shardmgr
node_db -->|"loads and updates"| node_config
node_shardmgr -->|"hash routes keys"| node_shard
node_shardmgr -->|"dispatches bulk work"| node_bulk
node_bulk -->|"enqueues shard tasks"| node_threadpool
node_shard -->|"looks up and updates"| node_index
node_shard -->|"reads and appends values"| node_segments
node_shard -->|"uses hot entries"| node_cache
node_shard -->|"records mutations"| node_wal
node_shard -->|"records operation metrics"| node_monitor
node_http -->|"exposes statistics"| node_monitor
node_maintenance -->|"compacts index"| node_index
node_maintenance -->|"removes obsolete segments"| node_segments
node_db -->|"flushes periodically"| node_maintenance
node_db -->|"creates archives"| node_archive
node_db -->|"replays on startup"| node_wal
node_db -->|"logs activity"| node_logger

click node_session "https://github.com/benahmed-adam/zestdb/blob/main/src/Server.cpp"
click node_tcp "https://github.com/benahmed-adam/zestdb/blob/main/src/Server.cpp"
click node_db "https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp"
click node_config "https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp"
click node_shardmgr "https://github.com/benahmed-adam/zestdb/blob/main/src/ShardManager.cpp"
click node_bulk "https://github.com/benahmed-adam/zestdb/blob/main/src/ShardManager.cpp"
click node_shard "https://github.com/benahmed-adam/zestdb/blob/main/src/Shard.cpp"
click node_index "https://github.com/benahmed-adam/zestdb/blob/main/src/IndexManager.cpp"
click node_segments "https://github.com/benahmed-adam/zestdb/blob/main/src/StorageManager.cpp"
click node_cache "https://github.com/benahmed-adam/zestdb/blob/main/src/LRUCache.cpp"
click node_wal "https://github.com/benahmed-adam/zestdb/blob/main/src/WAL.cpp"
click node_monitor "https://github.com/benahmed-adam/zestdb/blob/main/src/PerfMonitoring.cpp"
click node_http "https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp"
click node_maintenance "https://github.com/benahmed-adam/zestdb/blob/main/src/Shard.cpp"
click node_archive "https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp"
click node_logger "https://github.com/benahmed-adam/zestdb/blob/main/src/Logger.cpp"
click node_threadpool "https://github.com/benahmed-adam/zestdb/blob/main/src/ThreadPool.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_session,node_tcp,node_client toneBlue
class node_db,node_config toneAmber
class node_shardmgr,node_bulk,node_shard,node_threadpool toneMint
class node_index,node_segments,node_cache,node_wal toneRose
class node_monitor,node_http,node_maintenance,node_archive,node_logger toneIndigo
```

## Components

### Client access

- [Session framing](https://github.com/benahmed-adam/zestdb/blob/main/src/Server.cpp): `src/Server.cpp`
- [TCP server](https://github.com/benahmed-adam/zestdb/blob/main/src/Server.cpp): `src/Server.cpp`

### Command and control

- [Database facade](https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp): `src/ZestDB.cpp`
- [Config management](https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp): `src/ZestDB.cpp`

### Sharded execution

- [Shard routing](https://github.com/benahmed-adam/zestdb/blob/main/src/ShardManager.cpp): `src/ShardManager.cpp`
- [Parallel bulk ops](https://github.com/benahmed-adam/zestdb/blob/main/src/ShardManager.cpp): `src/ShardManager.cpp`
- [Shard engine](https://github.com/benahmed-adam/zestdb/blob/main/src/Shard.cpp): `src/Shard.cpp`
- [Worker pool](https://github.com/benahmed-adam/zestdb/blob/main/src/ThreadPool.cpp): `src/ThreadPool.cpp`

### Durable storage

- [In-memory index](https://github.com/benahmed-adam/zestdb/blob/main/src/IndexManager.cpp): `src/IndexManager.cpp`
- [Segment storage](https://github.com/benahmed-adam/zestdb/blob/main/src/StorageManager.cpp): `src/StorageManager.cpp`
- [LRU cache](https://github.com/benahmed-adam/zestdb/blob/main/src/LRUCache.cpp): `src/LRUCache.cpp`
- [Write-ahead log](https://github.com/benahmed-adam/zestdb/blob/main/src/WAL.cpp): `src/WAL.cpp`

### Operations and observability

- [Performance counters](https://github.com/benahmed-adam/zestdb/blob/main/src/PerfMonitoring.cpp): `src/PerfMonitoring.cpp`
- [HTTP metrics](https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp): `src/ZestDB.cpp`
- [Flush and compaction](https://github.com/benahmed-adam/zestdb/blob/main/src/Shard.cpp): `src/Shard.cpp`
- [Database archiving](https://github.com/benahmed-adam/zestdb/blob/main/src/ZestDB.cpp): `src/ZestDB.cpp`
- [Logging](https://github.com/benahmed-adam/zestdb/blob/main/src/Logger.cpp): `src/Logger.cpp`

### Other components

- **TCP client**

## Connections

- TCP client → TCP server: sends commands (evidence: `README.md`)
- TCP server → Session framing: accepts sessions (evidence: `src/Server.cpp`)
- Session framing → Database facade: dispatches commands (evidence: `src/Server.cpp`)
- Database facade → Shard routing: routes operations (evidence: `README.md`)
- Database facade → Config management: loads and updates (evidence: `src/ZestDB.cpp`)
- Shard routing → Shard engine: hash routes keys (evidence: `src/ShardManager.cpp`)
- Shard routing → Parallel bulk ops: dispatches bulk work (evidence: `src/ShardManager.cpp`)
- Parallel bulk ops → Worker pool: enqueues shard tasks (evidence: `src/ShardManager.cpp`)
- Shard engine → In-memory index: looks up and updates
- Shard engine → Segment storage: reads and appends values (evidence: `src/StorageManager.cpp`)
- Shard engine → LRU cache: uses hot entries
- Shard engine → Write-ahead log: records mutations (evidence: `README.md`)
- Shard engine → Performance counters: records operation metrics (evidence: `README.md`)
- HTTP metrics → Performance counters: exposes statistics (evidence: `README.md`)
- Flush and compaction → In-memory index: compacts index (evidence: `README.md`)
- Flush and compaction → Segment storage: removes obsolete segments (evidence: `README.md`)
- Database facade → Flush and compaction: flushes periodically (evidence: `README.md`)
- Database facade → Database archiving: creates archives (evidence: `README.md`)
- Database facade → Write-ahead log: replays on startup
- Database facade → Logging: logs activity (evidence: `src/ZestDB.cpp`)
