# apache/kvrocks architecture

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

- Interactive diagram: https://gitdiagram.com/apache/kvrocks
- Repository: https://github.com/apache/kvrocks

## Overview

Kvrocks is a Redis-protocol-compatible distributed key-value database backed by RocksDB. The principal workflow is a Redis client sending a command over the server connection; command handling accesses namespaced data in storage and returns a protocol reply. Major documented branches include search/indexing, replication, and proxyless clustering. Paths for these branches are supported by the tree and README, but their detailed wiring was not sampled; the graph therefore shows only high-level documented relationships there.

Main entry points: [`src/commands`](https://github.com/apache/kvrocks/tree/unstable/src/commands) (Redis commands), [`src/search/index_manager.cc`](https://github.com/apache/kvrocks/blob/unstable/src/search/index_manager.cc) (Index management), [`src/server/redis_connection.cc`](https://github.com/apache/kvrocks/blob/unstable/src/server/redis_connection.cc) (Redis connection), [`src/storage/storage.cc`](https://github.com/apache/kvrocks/blob/unstable/src/storage/storage.cc) (Storage engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Protocol serving"]
  node_server["Kvrocks server<br/>[server.cc]"]
  node_connection["Redis connection"]
  node_worker["Connection worker<br/>[worker.cc]"]
  node_request["Request parsing<br/>[redis_request.cc]"]
  node_commander["Command dispatch<br/>[commander.cc]"]
  node_commands["Redis commands"]
  node_reply["Redis replies<br/>[redis_reply.cc]"]
end

subgraph group_data["Data and storage"]
  node_namespace["Namespace isolation<br/>[namespace.cc]"]
  node_types["Redis data types"]
  node_storage["Storage engine<br/>[storage.cc]"]
  node_rocksdb[("RocksDB")]
end

subgraph group_search["Search and indexing"]
  node_search_commands["Search commands<br/>[cmd_search.cc]"]
  node_query["Query parsing"]
  node_indexes["Index management<br/>[index_manager.cc]"]
  node_planner["Query planning<br/>[manager.h]"]
  node_executor["Plan execution<br/>[plan_executor.cc]"]
  node_indexer["Index building<br/>[indexer.cc]"]
end

subgraph group_distributed["Distributed features"]
  node_cluster["Cluster slots<br/>[cluster.cc]"]
  node_migration["Slot migration<br/>[slot_migrate.cc]"]
  node_replication["Async replication<br/>[replication.cc]"]
end

subgraph group_operations["Operations"]
  node_config["Configuration<br/>[config.cc]"]
  node_stats["Stats and metrics<br/>[stats.cc]"]
  node_backup["Backup and restore<br/>[storage.cc]"]
end

node_client(("Redis client"))
node_sentinel(("Redis Sentinel"))

node_client -->|"sends commands"| node_connection
node_connection -->|"dispatches requests"| node_worker
node_worker -->|"parses input"| node_request
node_request -->|"dispatches command"| node_commander
node_commander -->|"invokes handler"| node_commands
node_commands -->|"selects namespace"| node_namespace
node_commands -->|"operates on values"| node_types
node_commands -->|"reads and writes"| node_storage
node_storage -->|"persists data"| node_rocksdb
node_commands -->|"produces response"| node_reply
node_reply -->|"returns protocol data"| node_connection
node_search_commands -->|"parses queries"| node_query
node_search_commands -->|"manages and searches"| node_indexes
node_indexes -->|"generates plans"| node_planner
node_planner -->|"lowers query plan"| node_executor
node_executor -->|"reads indexed data"| node_storage
node_indexes -->|"builds indexes"| node_indexer
node_cluster -->|"coordinates slot moves"| node_migration
node_replication -.->|"supports failover"| node_sentinel
node_server -->|"uses configuration"| node_config
node_server -->|"reports metrics"| node_stats
node_backup -->|"creates checkpoints"| node_rocksdb

click node_server "https://github.com/apache/kvrocks/blob/unstable/src/server/server.cc"
click node_connection "https://github.com/apache/kvrocks/blob/unstable/src/server/redis_connection.cc"
click node_worker "https://github.com/apache/kvrocks/blob/unstable/src/server/worker.cc"
click node_request "https://github.com/apache/kvrocks/blob/unstable/src/server/redis_request.cc"
click node_commander "https://github.com/apache/kvrocks/blob/unstable/src/commands/commander.cc"
click node_commands "https://github.com/apache/kvrocks/tree/unstable/src/commands"
click node_reply "https://github.com/apache/kvrocks/blob/unstable/src/server/redis_reply.cc"
click node_namespace "https://github.com/apache/kvrocks/blob/unstable/src/server/namespace.cc"
click node_types "https://github.com/apache/kvrocks/tree/unstable/src/types"
click node_storage "https://github.com/apache/kvrocks/blob/unstable/src/storage/storage.cc"
click node_search_commands "https://github.com/apache/kvrocks/blob/unstable/src/commands/cmd_search.cc"
click node_query "https://github.com/apache/kvrocks/blob/unstable/src/search/redis_query_transformer.h"
click node_indexes "https://github.com/apache/kvrocks/blob/unstable/src/search/index_manager.cc"
click node_planner "https://github.com/apache/kvrocks/blob/unstable/src/search/passes/manager.h"
click node_executor "https://github.com/apache/kvrocks/blob/unstable/src/search/plan_executor.cc"
click node_indexer "https://github.com/apache/kvrocks/blob/unstable/src/search/indexer.cc"
click node_cluster "https://github.com/apache/kvrocks/blob/unstable/src/cluster/cluster.cc"
click node_migration "https://github.com/apache/kvrocks/blob/unstable/src/cluster/slot_migrate.cc"
click node_replication "https://github.com/apache/kvrocks/blob/unstable/src/cluster/replication.cc"
click node_config "https://github.com/apache/kvrocks/blob/unstable/src/config/config.cc"
click node_stats "https://github.com/apache/kvrocks/blob/unstable/src/stats/stats.cc"
click node_backup "https://github.com/apache/kvrocks/blob/unstable/src/storage/storage.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_server,node_connection,node_worker,node_request,node_commander,node_commands,node_reply toneBlue
class node_namespace,node_types,node_storage,node_rocksdb,node_client,node_sentinel toneAmber
class node_search_commands,node_query,node_indexes,node_planner,node_executor,node_indexer toneMint
class node_cluster,node_migration,node_replication toneRose
class node_config,node_stats,node_backup toneIndigo
```

## Components

### Protocol serving

- [Kvrocks server](https://github.com/apache/kvrocks/blob/unstable/src/server/server.cc): `src/server/server.cc`
- [Redis connection](https://github.com/apache/kvrocks/blob/unstable/src/server/redis_connection.cc): `src/server/redis_connection.cc`
- [Connection worker](https://github.com/apache/kvrocks/blob/unstable/src/server/worker.cc): `src/server/worker.cc`
- [Request parsing](https://github.com/apache/kvrocks/blob/unstable/src/server/redis_request.cc): `src/server/redis_request.cc`
- [Command dispatch](https://github.com/apache/kvrocks/blob/unstable/src/commands/commander.cc): `src/commands/commander.cc`
- [Redis commands](https://github.com/apache/kvrocks/tree/unstable/src/commands): `src/commands`
- [Redis replies](https://github.com/apache/kvrocks/blob/unstable/src/server/redis_reply.cc): `src/server/redis_reply.cc`

### Data and storage

- [Namespace isolation](https://github.com/apache/kvrocks/blob/unstable/src/server/namespace.cc): `src/server/namespace.cc`
- [Redis data types](https://github.com/apache/kvrocks/tree/unstable/src/types): `src/types`
- [Storage engine](https://github.com/apache/kvrocks/blob/unstable/src/storage/storage.cc): `src/storage/storage.cc`
- **RocksDB**

### Search and indexing

- [Search commands](https://github.com/apache/kvrocks/blob/unstable/src/commands/cmd_search.cc): `src/commands/cmd_search.cc`
- [Query parsing](https://github.com/apache/kvrocks/blob/unstable/src/search/redis_query_transformer.h): `src/search/redis_query_transformer.h`
- [Index management](https://github.com/apache/kvrocks/blob/unstable/src/search/index_manager.cc): `src/search/index_manager.cc`
- [Query planning](https://github.com/apache/kvrocks/blob/unstable/src/search/passes/manager.h): `src/search/passes/manager.h`
- [Plan execution](https://github.com/apache/kvrocks/blob/unstable/src/search/plan_executor.cc): `src/search/plan_executor.cc`
- [Index building](https://github.com/apache/kvrocks/blob/unstable/src/search/indexer.cc): `src/search/indexer.cc`

### Distributed features

- [Cluster slots](https://github.com/apache/kvrocks/blob/unstable/src/cluster/cluster.cc): `src/cluster/cluster.cc`
- [Slot migration](https://github.com/apache/kvrocks/blob/unstable/src/cluster/slot_migrate.cc): `src/cluster/slot_migrate.cc`
- [Async replication](https://github.com/apache/kvrocks/blob/unstable/src/cluster/replication.cc): `src/cluster/replication.cc`

### Operations

- [Configuration](https://github.com/apache/kvrocks/blob/unstable/src/config/config.cc): `src/config/config.cc`
- [Stats and metrics](https://github.com/apache/kvrocks/blob/unstable/src/stats/stats.cc): `src/stats/stats.cc`
- [Backup and restore](https://github.com/apache/kvrocks/blob/unstable/src/storage/storage.cc): `src/storage/storage.cc`

### Other components

- **Redis client**
- **Redis Sentinel**

## Connections

- Redis client → Redis connection: sends commands
- Redis connection → Connection worker: dispatches requests
- Connection worker → Request parsing: parses input
- Request parsing → Command dispatch: dispatches command
- Command dispatch → Redis commands: invokes handler
- Redis commands → Namespace isolation: selects namespace
- Redis commands → Redis data types: operates on values
- Redis commands → Storage engine: reads and writes
- Storage engine → RocksDB: persists data
- Redis commands → Redis replies: produces response
- Redis replies → Redis connection: returns protocol data
- Search commands → Query parsing: parses queries
- Search commands → Index management: manages and searches
- Index management → Query planning: generates plans
- Query planning → Plan execution: lowers query plan
- Plan execution → Storage engine: reads indexed data
- Index management → Index building: builds indexes
- Cluster slots → Slot migration: coordinates slot moves
- Async replication → Redis Sentinel: supports failover
- Kvrocks server → Configuration: uses configuration
- Kvrocks server → Stats and metrics: reports metrics
- Backup and restore → RocksDB: creates checkpoints