# theproject24/titan_kv architecture

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

- Interactive diagram: https://gitdiagram.com/theproject24/titan_kv
- Repository: https://github.com/theproject24/titan_kv

## Overview

Titan KV is a Redis-compatible in-memory key-value server. A client sends RESP (or simple text) over TCP; the server parses and dispatches commands, then returns RESP results. The engine supports strings, lists, hashes, sets, TTLs, key scans, and cross-shard operations; pub/sub and monitoring provide separate event-stream features. Startup restores state from AOF, while background workers persist writes, expire keys, and compact the log. The README documents these capabilities; sampled source excerpts are partial, so uncertain command-level wiring is omitted.

Main entry points: [`src/main.rs`](https://github.com/theproject24/titan_kv/blob/master/src/main.rs) (Startup orchestrator), [`src/server.rs`](https://github.com/theproject24/titan_kv/blob/master/src/server.rs) (TCP command server), [`src/engine.rs`](https://github.com/theproject24/titan_kv/blob/master/src/engine.rs) (Sharded store), [`database.aof`](https://github.com/theproject24/titan_kv/blob/master/database.aof) (database.aof)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_network["Client and protocol"]
  node_server["TCP command server<br/>[server.rs]"]
  node_protocol["RESP parser<br/>[protocol.rs]"]
end

subgraph group_runtime["Server runtime"]
  node_config["Runtime config<br/>[config.rs]"]
  node_main["Startup orchestrator<br/>[main.rs]"]
  node_logger["Logging<br/>[logger.rs]"]
end

subgraph group_data["Database features"]
  node_engine[("Sharded store<br/>[engine.rs]")]
  node_pubsub["Pub/sub broker<br/>[pubsub.rs]"]
  node_monitor["Monitor stream<br/>[engine.rs]"]
end

subgraph group_durability["AOF durability"]
  node_replay["AOF replay<br/>[main.rs]"]
  node_aof_queue["AOF write queue<br/>[engine.rs]"]
  node_writer["AOF writer<br/>[main.rs]"]
  node_sweeper["TTL sweeper<br/>[main.rs]"]
  node_compactor["AOF compactor<br/>[main.rs]"]
  node_aof_file[("database.aof<br/>[database.aof]")]
end

node_clients(("Redis clients"))

node_clients -->|"send TCP"| node_server
node_server -->|"return RESP"| node_clients
node_server -->|"read and parse"| node_protocol
node_server -->|"execute commands"| node_engine
node_server -->|"publish and subscribe"| node_pubsub
node_server -->|"stream activity"| node_monitor
node_main -->|"parse settings"| node_config
node_main -->|"launch listener"| node_server
node_main -->|"initialize store"| node_engine
node_main -->|"restore state"| node_replay
node_replay -->|"read log"| node_aof_file
node_replay -->|"tokenize commands"| node_protocol
node_replay -->|"rebuild state"| node_engine
node_engine -->|"enqueue writes"| node_aof_queue
node_aof_queue -->|"deliver log entries"| node_writer
node_writer -->|"append writes"| node_aof_file
node_main -->|"start worker"| node_sweeper
node_sweeper -->|"scan and delete"| node_engine
node_sweeper -->|"append deletions"| node_aof_file
node_main -->|"start worker"| node_compactor
node_compactor -->|"read current state"| node_engine
node_compactor -->|"replace compacted log"| node_aof_file
node_main -->|"log lifecycle"| node_logger

click node_server "https://github.com/theproject24/titan_kv/blob/master/src/server.rs"
click node_protocol "https://github.com/theproject24/titan_kv/blob/master/src/protocol.rs"
click node_config "https://github.com/theproject24/titan_kv/blob/master/src/config.rs"
click node_main "https://github.com/theproject24/titan_kv/blob/master/src/main.rs"
click node_logger "https://github.com/theproject24/titan_kv/blob/master/src/logger.rs"
click node_engine "https://github.com/theproject24/titan_kv/blob/master/src/engine.rs"
click node_pubsub "https://github.com/theproject24/titan_kv/blob/master/src/pubsub.rs"
click node_monitor "https://github.com/theproject24/titan_kv/blob/master/src/engine.rs"
click node_replay "https://github.com/theproject24/titan_kv/blob/master/src/main.rs"
click node_aof_queue "https://github.com/theproject24/titan_kv/blob/master/src/engine.rs"
click node_writer "https://github.com/theproject24/titan_kv/blob/master/src/main.rs"
click node_sweeper "https://github.com/theproject24/titan_kv/blob/master/src/main.rs"
click node_compactor "https://github.com/theproject24/titan_kv/blob/master/src/main.rs"
click node_aof_file "https://github.com/theproject24/titan_kv/blob/master/database.aof"

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_protocol toneBlue
class node_config,node_main,node_logger,node_clients toneAmber
class node_engine,node_pubsub,node_monitor toneMint
class node_replay,node_aof_queue,node_writer,node_sweeper,node_compactor,node_aof_file toneRose
```

## Components

### Client and protocol

- [TCP command server](https://github.com/theproject24/titan_kv/blob/master/src/server.rs): `src/server.rs`
- [RESP parser](https://github.com/theproject24/titan_kv/blob/master/src/protocol.rs): `src/protocol.rs`

### Server runtime

- [Runtime config](https://github.com/theproject24/titan_kv/blob/master/src/config.rs): `src/config.rs`
- [Startup orchestrator](https://github.com/theproject24/titan_kv/blob/master/src/main.rs): `src/main.rs`
- [Logging](https://github.com/theproject24/titan_kv/blob/master/src/logger.rs): `src/logger.rs`

### Database features

- [Sharded store](https://github.com/theproject24/titan_kv/blob/master/src/engine.rs): `src/engine.rs`
- [Pub/sub broker](https://github.com/theproject24/titan_kv/blob/master/src/pubsub.rs): `src/pubsub.rs`
- [Monitor stream](https://github.com/theproject24/titan_kv/blob/master/src/engine.rs): `src/engine.rs`

### AOF durability

- [AOF replay](https://github.com/theproject24/titan_kv/blob/master/src/main.rs): `src/main.rs`
- [AOF write queue](https://github.com/theproject24/titan_kv/blob/master/src/engine.rs): `src/engine.rs`
- [AOF writer](https://github.com/theproject24/titan_kv/blob/master/src/main.rs): `src/main.rs`
- [TTL sweeper](https://github.com/theproject24/titan_kv/blob/master/src/main.rs): `src/main.rs`
- [AOF compactor](https://github.com/theproject24/titan_kv/blob/master/src/main.rs): `src/main.rs`
- [database.aof](https://github.com/theproject24/titan_kv/blob/master/database.aof): `database.aof`

### Other components

- **Redis clients**

## Connections

- Redis clients → TCP command server: send TCP
- TCP command server → Redis clients: return RESP
- TCP command server → RESP parser: read and parse
- TCP command server → Sharded store: execute commands
- TCP command server → Pub/sub broker: publish and subscribe
- TCP command server → Monitor stream: stream activity
- Startup orchestrator → Runtime config: parse settings
- Startup orchestrator → TCP command server: launch listener
- Startup orchestrator → Sharded store: initialize store
- Startup orchestrator → AOF replay: restore state
- AOF replay → database.aof: read log
- AOF replay → RESP parser: tokenize commands
- AOF replay → Sharded store: rebuild state
- Sharded store → AOF write queue: enqueue writes
- AOF write queue → AOF writer: deliver log entries
- AOF writer → database.aof: append writes
- Startup orchestrator → TTL sweeper: start worker
- TTL sweeper → Sharded store: scan and delete
- TTL sweeper → database.aof: append deletions
- Startup orchestrator → AOF compactor: start worker
- AOF compactor → Sharded store: read current state
- AOF compactor → database.aof: replace compacted log
- Startup orchestrator → Logging: log lifecycle