# nitin27pro/distributed-key-value-store architecture

> Architecture diagram of the GitHub repository nitin27pro/distributed-key-value-store, 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/nitin27pro/distributed-key-value-store
- Repository: https://github.com/nitin27pro/distributed-key-value-store

## Overview

This is a C++ distributed key-value store: clients issue text commands to a primary, which serves reads locally and synchronously replicates writes to healthy backups before acknowledging them. Sequence-numbered WALs support restart replay and replica catch-up; a health monitor retries recovery while the primary remains online. The repository also includes an earlier standalone TCP server in `kv_server_week4.cpp`, separate from the replicated runtime. Relationships reflect the excerpts and README; unsampled details are omitted.

Main entry points: [`primary_node.cpp`](https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp) (Command handler), [`backup_node.cpp`](https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp) (Backup protocol), [`kv_server_week4.cpp`](https://github.com/nitin27pro/distributed-key-value-store/blob/main/kv_server_week4.cpp) (Standalone server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_primary["Primary runtime"]
  node_primary_server["Primary server<br/>[primary_node.cpp]"]
  node_command_handler["Command handler<br/>[primary_node.cpp]"]
  node_primary_lru["Primary LRU<br/>[primary_node.cpp]"]
  node_primary_wal[("Primary WAL<br/>[primary_node.cpp]")]
  node_replication_manager["Replication manager<br/>[primary_node.cpp]"]
  node_health_monitor["Health monitor<br/>[primary_node.cpp]"]
end

subgraph group_replicas["Replica runtime"]
  node_backup_server["Backup server<br/>[backup_node.cpp]"]
  node_backup_protocol["Backup protocol<br/>[backup_node.cpp]"]
  node_backup_lru["Backup LRU<br/>[backup_node.cpp]"]
  node_backup_wal[("Backup WAL<br/>[backup_node.cpp]")]
end

subgraph group_standalone["Standalone server"]
  node_standalone_server["Standalone server"]
  node_standalone_commands["Command handler"]
  node_standalone_lru["LRU engine"]
end

node_client(("Client"))
node_old_client(("Client"))

node_client -->|"sends commands"| node_primary_server
node_primary_server -->|"dispatches"| node_command_handler
node_command_handler -->|"serves reads"| node_primary_lru
node_command_handler -->|"replicates writes"| node_replication_manager
node_command_handler -->|"applies writes"| node_primary_lru
node_command_handler -->|"appends writes"| node_primary_wal
node_health_monitor -->|"drives recovery"| node_replication_manager
node_replication_manager -->|"reads catch-up entries"| node_primary_wal
node_replication_manager -->|"sends SEQWRITE"| node_backup_server
node_health_monitor -->|"probes GETSEQ"| node_backup_server
node_backup_server -->|"handles connections"| node_backup_protocol
node_backup_protocol -->|"applies writes"| node_backup_lru
node_backup_protocol -->|"persists writes"| node_backup_wal
node_old_client -->|"connects over TCP"| node_standalone_server
node_standalone_server -->|"dispatches lines"| node_standalone_commands
node_standalone_commands -->|"reads and writes"| node_standalone_lru

click node_primary_server "https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp"
click node_command_handler "https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp"
click node_primary_lru "https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp"
click node_primary_wal "https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp"
click node_replication_manager "https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp"
click node_health_monitor "https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp"
click node_backup_server "https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp"
click node_backup_protocol "https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp"
click node_backup_lru "https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp"
click node_backup_wal "https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp"
click node_standalone_server "https://github.com/nitin27pro/distributed-key-value-store/blob/main/kv_server_week4.cpp"
click node_standalone_commands "https://github.com/nitin27pro/distributed-key-value-store/blob/main/kv_server_week4.cpp"
click node_standalone_lru "https://github.com/nitin27pro/distributed-key-value-store/blob/main/kv_server_week4.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_primary_server,node_command_handler,node_primary_lru,node_primary_wal,node_replication_manager,node_health_monitor,node_client,node_old_client toneBlue
class node_backup_server,node_backup_protocol,node_backup_lru,node_backup_wal toneAmber
class node_standalone_server,node_standalone_commands,node_standalone_lru toneMint
```

## Components

### Primary runtime

- [Primary server](https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp): `primary_node.cpp`
- [Command handler](https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp): `primary_node.cpp`
- [Primary LRU](https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp): `primary_node.cpp`
- [Primary WAL](https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp): `primary_node.cpp`
- [Replication manager](https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp): `primary_node.cpp`
- [Health monitor](https://github.com/nitin27pro/distributed-key-value-store/blob/main/primary_node.cpp): `primary_node.cpp`

### Replica runtime

- [Backup server](https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp): `backup_node.cpp`
- [Backup protocol](https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp): `backup_node.cpp`
- [Backup LRU](https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp): `backup_node.cpp`
- [Backup WAL](https://github.com/nitin27pro/distributed-key-value-store/blob/main/backup_node.cpp): `backup_node.cpp`

### Standalone server

- [Standalone server](https://github.com/nitin27pro/distributed-key-value-store/blob/main/kv_server_week4.cpp): `kv_server_week4.cpp`
- [Command handler](https://github.com/nitin27pro/distributed-key-value-store/blob/main/kv_server_week4.cpp): `kv_server_week4.cpp`
- [LRU engine](https://github.com/nitin27pro/distributed-key-value-store/blob/main/kv_server_week4.cpp): `kv_server_week4.cpp`

### Other components

- **Client**
- **Client**

## Connections

- Client → Primary server: sends commands (evidence: `README.md`)
- Primary server → Command handler: dispatches (evidence: `README.md`)
- Command handler → Primary LRU: serves reads (evidence: `primary_node.cpp`)
- Command handler → Replication manager: replicates writes (evidence: `primary_node.cpp`)
- Command handler → Primary LRU: applies writes (evidence: `primary_node.cpp`)
- Command handler → Primary WAL: appends writes (evidence: `primary_node.cpp`)
- Health monitor → Replication manager: drives recovery (evidence: `primary_node.cpp`)
- Replication manager → Primary WAL: reads catch-up entries (evidence: `README.md`)
- Replication manager → Backup server: sends SEQWRITE (evidence: `README.md`)
- Health monitor → Backup server: probes GETSEQ (evidence: `primary_node.cpp`)
- Backup server → Backup protocol: handles connections (evidence: `backup_node.cpp`)
- Backup protocol → Backup LRU: applies writes (evidence: `backup_node.cpp`)
- Backup protocol → Backup WAL: persists writes (evidence: `backup_node.cpp`)
- Client → Standalone server: connects over TCP (evidence: `kv_server_week4.cpp`)
- Standalone server → Command handler: dispatches lines (evidence: `kv_server_week4.cpp`)
- Command handler → LRU engine: reads and writes (evidence: `kv_server_week4.cpp`)
