# ichbingautam/quinedb architecture

> Architecture diagram of the GitHub repository ichbingautam/quinedb, 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/ichbingautam/quinedb
- Repository: https://github.com/ichbingautam/quinedb

## Overview

QuineDB is a Redis-compatible, distributed in-memory key-value server. A client sends RESP commands over TCP; the server parses and dispatches them, and commands operate on the key’s owning per-core shard or forward requests to that core and return responses. The graph also captures persistence, asynchronous I/O, and the documented TTL and consensus capabilities. Some internal network and command details are unsampled; their links are omitted or marked unverified where the evidence does not establish a call.

Main entry points: [`src/main.cpp`](https://github.com/ichbingautam/quinedb/blob/main/src/main.cpp) (Command dispatch), [`src/core/topology.hpp`](https://github.com/ichbingautam/quinedb/blob/main/src/core/topology.hpp) (Core topology), [`src/storage/shard.cpp`](https://github.com/ichbingautam/quinedb/blob/main/src/storage/shard.cpp) (Per-core shards), [`src/network/tcp_server.cpp`](https://github.com/ichbingautam/quinedb/blob/main/src/network/tcp_server.cpp) (TCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_network["Client networking"]
  node_server["TCP server<br/>[tcp_server.cpp]"]
  node_connection["Connections<br/>[connection.cpp]"]
  node_resp["RESP parser<br/>[resp_parser.cpp]"]
end

subgraph group_runtime["Core runtime"]
  node_eventloop["Async I/O loop<br/>[io_context.cpp]"]
  node_topology["Core topology<br/>[topology.hpp]"]
  node_router["Key router<br/>[router.cpp]"]
  node_channels["Core message channels<br/>[itc_channel.hpp]"]
  node_dispatcher["Command dispatch<br/>[main.cpp]"]
  node_consensus["Raft skeleton<br/>[raft.hpp]"]
end

subgraph group_commands["Command operations"]
  node_strings["String commands"]
  node_lists["List commands<br/>[list_commands.hpp]"]
  node_sets["Set commands<br/>[set_commands.hpp]"]
  node_hashes["Hash commands<br/>[hash_commands.hpp]"]
  node_sortedsets["Sorted-set commands<br/>[zset_commands.hpp]"]
  node_generic["Generic and TTL"]
  node_admin["Admin commands<br/>[admin_commands.hpp]"]
end

subgraph group_data["Storage and durability"]
  node_shards[("Per-core shards<br/>[shard.cpp]")]
  node_values["Data structures<br/>[value.hpp]"]
  node_persistence["RDB snapshots<br/>[rdb_manager.hpp]"]
end

node_client(("Redis client"))

node_client -->|"sends commands"| node_server
node_server -->|"accepts connections"| node_connection
node_connection -.->|"parses input"| node_resp
node_connection -->|"submits I/O"| node_eventloop
node_server -->|"uses event loop"| node_eventloop
node_dispatcher -->|"runs per core"| node_eventloop
node_dispatcher -->|"initializes workers"| node_topology
node_dispatcher -->|"starts server"| node_server
node_dispatcher -->|"loads snapshot"| node_persistence
node_dispatcher -->|"registers commands"| node_strings
node_dispatcher -->|"registers commands"| node_lists
node_dispatcher -->|"registers commands"| node_sets
node_dispatcher -->|"registers commands"| node_hashes
node_dispatcher -->|"registers commands"| node_sortedsets
node_dispatcher -->|"registers commands"| node_admin
node_dispatcher -->|"registers commands"| node_generic
node_dispatcher -->|"handles messages"| node_channels
node_topology -->|"routes keys"| node_router
node_topology -->|"owns shards"| node_shards
node_topology -->|"owns channels"| node_channels
node_strings -.->|"checks ownership"| node_topology
node_lists -->|"checks ownership"| node_topology
node_sets -.->|"routes keys"| node_topology
node_hashes -.->|"routes keys"| node_topology
node_sortedsets -.->|"routes keys"| node_topology
node_generic -.->|"uses topology"| node_topology
node_admin -.->|"saves snapshot"| node_persistence
node_persistence -->|"loads into shards"| node_topology
node_persistence -->|"reads snapshots"| node_shards
node_shards -->|"stores values"| node_values
node_strings -.->|"reads and writes"| node_shards
node_lists -->|"reads and writes"| node_shards
node_sets -.->|"reads and writes"| node_shards
node_hashes -.->|"reads and writes"| node_shards
node_sortedsets -.->|"reads and writes"| node_shards
node_generic -.->|"manages expiry"| node_shards
node_topology -.->|"cluster direction"| node_consensus

click node_server "https://github.com/ichbingautam/quinedb/blob/main/src/network/tcp_server.cpp"
click node_connection "https://github.com/ichbingautam/quinedb/blob/main/src/network/connection.cpp"
click node_resp "https://github.com/ichbingautam/quinedb/blob/main/src/network/resp_parser.cpp"
click node_eventloop "https://github.com/ichbingautam/quinedb/blob/main/src/core/io_context.cpp"
click node_topology "https://github.com/ichbingautam/quinedb/blob/main/src/core/topology.hpp"
click node_router "https://github.com/ichbingautam/quinedb/blob/main/src/core/router.cpp"
click node_channels "https://github.com/ichbingautam/quinedb/blob/main/src/core/itc_channel.hpp"
click node_dispatcher "https://github.com/ichbingautam/quinedb/blob/main/src/main.cpp"
click node_strings "https://github.com/ichbingautam/quinedb/blob/main/src/commands/string_commands.hpp"
click node_lists "https://github.com/ichbingautam/quinedb/blob/main/src/commands/list_commands.hpp"
click node_sets "https://github.com/ichbingautam/quinedb/blob/main/src/commands/set_commands.hpp"
click node_hashes "https://github.com/ichbingautam/quinedb/blob/main/src/commands/hash_commands.hpp"
click node_sortedsets "https://github.com/ichbingautam/quinedb/blob/main/src/commands/zset_commands.hpp"
click node_generic "https://github.com/ichbingautam/quinedb/blob/main/src/commands/generic_commands.hpp"
click node_admin "https://github.com/ichbingautam/quinedb/blob/main/src/commands/admin_commands.hpp"
click node_shards "https://github.com/ichbingautam/quinedb/blob/main/src/storage/shard.cpp"
click node_values "https://github.com/ichbingautam/quinedb/blob/main/src/storage/value.hpp"
click node_persistence "https://github.com/ichbingautam/quinedb/blob/main/src/persistence/rdb_manager.hpp"
click node_consensus "https://github.com/ichbingautam/quinedb/blob/main/src/consensus/raft.hpp"

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_server,node_connection,node_resp toneBlue
class node_eventloop,node_topology,node_router,node_channels,node_dispatcher,node_consensus,node_client toneAmber
class node_strings,node_lists,node_sets,node_hashes,node_sortedsets,node_generic,node_admin toneMint
class node_shards,node_values,node_persistence toneRose
```

## Components

### Client networking

- [TCP server](https://github.com/ichbingautam/quinedb/blob/main/src/network/tcp_server.cpp): `src/network/tcp_server.cpp`
- [Connections](https://github.com/ichbingautam/quinedb/blob/main/src/network/connection.cpp): `src/network/connection.cpp`
- [RESP parser](https://github.com/ichbingautam/quinedb/blob/main/src/network/resp_parser.cpp): `src/network/resp_parser.cpp`

### Core runtime

- [Async I/O loop](https://github.com/ichbingautam/quinedb/blob/main/src/core/io_context.cpp): `src/core/io_context.cpp`
- [Core topology](https://github.com/ichbingautam/quinedb/blob/main/src/core/topology.hpp): `src/core/topology.hpp`
- [Key router](https://github.com/ichbingautam/quinedb/blob/main/src/core/router.cpp): `src/core/router.cpp`
- [Core message channels](https://github.com/ichbingautam/quinedb/blob/main/src/core/itc_channel.hpp): `src/core/itc_channel.hpp`
- [Command dispatch](https://github.com/ichbingautam/quinedb/blob/main/src/main.cpp): `src/main.cpp`
- [Raft skeleton](https://github.com/ichbingautam/quinedb/blob/main/src/consensus/raft.hpp): `src/consensus/raft.hpp`

### Command operations

- [String commands](https://github.com/ichbingautam/quinedb/blob/main/src/commands/string_commands.hpp): `src/commands/string_commands.hpp`
- [List commands](https://github.com/ichbingautam/quinedb/blob/main/src/commands/list_commands.hpp): `src/commands/list_commands.hpp`
- [Set commands](https://github.com/ichbingautam/quinedb/blob/main/src/commands/set_commands.hpp): `src/commands/set_commands.hpp`
- [Hash commands](https://github.com/ichbingautam/quinedb/blob/main/src/commands/hash_commands.hpp): `src/commands/hash_commands.hpp`
- [Sorted-set commands](https://github.com/ichbingautam/quinedb/blob/main/src/commands/zset_commands.hpp): `src/commands/zset_commands.hpp`
- [Generic and TTL](https://github.com/ichbingautam/quinedb/blob/main/src/commands/generic_commands.hpp): `src/commands/generic_commands.hpp`
- [Admin commands](https://github.com/ichbingautam/quinedb/blob/main/src/commands/admin_commands.hpp): `src/commands/admin_commands.hpp`

### Storage and durability

- [Per-core shards](https://github.com/ichbingautam/quinedb/blob/main/src/storage/shard.cpp): `src/storage/shard.cpp`
- [Data structures](https://github.com/ichbingautam/quinedb/blob/main/src/storage/value.hpp): `src/storage/value.hpp`
- [RDB snapshots](https://github.com/ichbingautam/quinedb/blob/main/src/persistence/rdb_manager.hpp): `src/persistence/rdb_manager.hpp`

### Other components

- **Redis client**

## Connections

- Redis client → TCP server: sends commands (evidence: `README.md`)
- TCP server → Connections: accepts connections (evidence: `src/network/tcp_server.cpp`)
- Connections → RESP parser: parses input
- Connections → Async I/O loop: submits I/O (evidence: `src/network/connection.cpp`)
- TCP server → Async I/O loop: uses event loop (evidence: `src/network/tcp_server.cpp`)
- Command dispatch → Async I/O loop: runs per core (evidence: `src/main.cpp`)
- Command dispatch → Core topology: initializes workers (evidence: `src/main.cpp`)
- Command dispatch → TCP server: starts server (evidence: `src/main.cpp`)
- Command dispatch → RDB snapshots: loads snapshot (evidence: `src/main.cpp`)
- Command dispatch → String commands: registers commands (evidence: `src/main.cpp`)
- Command dispatch → List commands: registers commands (evidence: `src/main.cpp`)
- Command dispatch → Set commands: registers commands (evidence: `src/main.cpp`)
- Command dispatch → Hash commands: registers commands (evidence: `src/main.cpp`)
- Command dispatch → Sorted-set commands: registers commands (evidence: `src/main.cpp`)
- Command dispatch → Admin commands: registers commands (evidence: `src/main.cpp`)
- Command dispatch → Generic and TTL: registers commands (evidence: `src/main.cpp`)
- Command dispatch → Core message channels: handles messages (evidence: `src/main.cpp`)
- Core topology → Key router: routes keys (evidence: `src/core/topology.hpp`)
- Core topology → Per-core shards: owns shards (evidence: `src/core/topology.hpp`)
- Core topology → Core message channels: owns channels (evidence: `src/core/topology.hpp`)
- String commands → Core topology: checks ownership (evidence: `src/commands/string_commands.hpp`)
- List commands → Core topology: checks ownership (evidence: `src/commands/list_commands.hpp`)
- Set commands → Core topology: routes keys (evidence: `src/commands/set_commands.hpp`)
- Hash commands → Core topology: routes keys (evidence: `src/commands/hash_commands.hpp`)
- Sorted-set commands → Core topology: routes keys (evidence: `src/commands/zset_commands.hpp`)
- Generic and TTL → Core topology: uses topology (evidence: `src/commands/generic_commands.hpp`)
- Admin commands → RDB snapshots: saves snapshot (evidence: `src/commands/admin_commands.hpp`)
- RDB snapshots → Core topology: loads into shards (evidence: `src/persistence/rdb_manager.hpp`)
- RDB snapshots → Per-core shards: reads snapshots (evidence: `src/persistence/rdb_manager.hpp`)
- Per-core shards → Data structures: stores values
- String commands → Per-core shards: reads and writes
- List commands → Per-core shards: reads and writes (evidence: `src/commands/list_commands.hpp`)
- Set commands → Per-core shards: reads and writes
- Hash commands → Per-core shards: reads and writes
- Sorted-set commands → Per-core shards: reads and writes
- Generic and TTL → Per-core shards: manages expiry
- Core topology → Raft skeleton: cluster direction
