# gkavinrajancodes/pulsedb architecture

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

- Interactive diagram: https://gitdiagram.com/gkavinrajancodes/pulsedb
- Repository: https://github.com/gkavinrajancodes/pulsedb

## Overview

PulseDB combines Redis-compatible in-memory storage and an HNSW vector engine behind RESP2 TCP and an HTTP command gateway. Its main workflow is client request → protocol/API entry point → command execution → KV, data-type, pub/sub, or vector operation, with persistence maintaining state. The graph also preserves documented cluster routing, LangChain retrieval, security, and observability. Edges are limited to relationships shown in excerpts or documented in the README; unsampled subsystems are included where documented, but their internal wiring is not inferred.

Main entry points: [`server/commands.py`](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/commands.py) (Command Executor), [`server/tcp_server.py`](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/tcp_server.py) (RESP2 TCP Server), [`server/main.py`](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/main.py) (HTTP Gateway), [`server/sleep_engine.py`](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/sleep_engine.py) (Memory Consolidation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client Interfaces"]
  node_syncsdk["Python SDK<br/>[client.py]"]
  node_asyncsdk["Async SDK<br/>[async_client.py]"]
  node_langchain["LangChain Store<br/>[vectorstore.py]"]
end

subgraph group_server["Server Entry Points"]
  node_httpapi["HTTP Gateway<br/>[main.py]"]
  node_tcp["RESP2 TCP Server<br/>[tcp_server.py]"]
  node_resp["RESP Encoder<br/>[resp.py]"]
  node_protocol["Binary Protocol<br/>[protocol.py]"]
end

subgraph group_commands["Command Processing"]
  node_router["Command Executor<br/>[commands.py]"]
  node_cluster["Cluster Routing<br/>[cluster.py]"]
end

subgraph group_data["Data Engines"]
  node_kv[("Sharded KV Store<br/>[store.py]")]
  node_types[("Lists and Hashes<br/>[data_types.py]")]
  node_vectors[("HNSW Vector Engine<br/>[vector.py]")]
  node_pubsub["Pub/Sub<br/>[pubsub.py]"]
  node_sleep["Memory Consolidation<br/>[sleep_engine.py]"]
end

subgraph group_operations["Operations"]
  node_persistence[("WAL and Snapshots<br/>[persistence.py]")]
  node_ttl["TTL Sweeper<br/>[ttl.py]"]
  node_config["Server Configuration<br/>[config.py]"]
  node_metrics["Health and Metrics<br/>[main.py]"]
end

node_developer(("Application / Client"))
node_rediscli(("Redis-compatible Client"))
node_external_llm(("OpenAI API"))

node_developer -->|"uses"| node_syncsdk
node_developer -->|"uses"| node_asyncsdk
node_developer -->|"ingests and searches"| node_langchain
node_syncsdk -->|"delegates"| node_asyncsdk
node_asyncsdk -->|"sends commands"| node_tcp
node_langchain -->|"uses SDK"| node_syncsdk
node_rediscli -->|"sends RESP2"| node_tcp
node_developer -->|"sends HTTP commands"| node_httpapi
node_httpapi -->|"executes commands"| node_router
node_tcp -->|"encodes RESP"| node_resp
node_tcp -->|"decodes binary protocol"| node_protocol
node_tcp -->|"dispatches commands"| node_router
node_router -->|"reads and writes"| node_kv
node_router -->|"dispatches type commands"| node_types
node_router -->|"dispatches vector commands"| node_vectors
node_router -->|"publishes messages"| node_pubsub
node_router -->|"logs writes"| node_persistence
node_router -->|"routes commands"| node_cluster
node_router -->|"runs consolidation"| node_sleep
node_ttl -->|"expires keys"| node_kv
node_httpapi -->|"streams subscriptions"| node_pubsub
node_persistence -->|"recovers and snapshots"| node_kv
node_vectors -->|"saves graph snapshots"| node_persistence
node_tcp -->|"loads auth and TLS settings"| node_config
node_httpapi -->|"checks API key"| node_config
node_httpapi -->|"exposes health and metrics"| node_metrics
node_sleep -->|"consolidates memories"| node_vectors
node_sleep -.->|"summarizes with"| node_external_llm

click node_syncsdk "https://github.com/gkavinrajancodes/pulsedb/blob/main/sdk/pulsedb/client.py"
click node_asyncsdk "https://github.com/gkavinrajancodes/pulsedb/blob/main/sdk/pulsedb/async_client.py"
click node_langchain "https://github.com/gkavinrajancodes/pulsedb/blob/main/sdk/langchain_pulsedb/vectorstore.py"
click node_httpapi "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/main.py"
click node_tcp "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/tcp_server.py"
click node_resp "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/resp.py"
click node_protocol "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/protocol.py"
click node_router "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/commands.py"
click node_cluster "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/cluster.py"
click node_kv "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/store.py"
click node_types "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/data_types.py"
click node_vectors "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/vector.py"
click node_pubsub "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/pubsub.py"
click node_sleep "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/sleep_engine.py"
click node_persistence "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/persistence.py"
click node_ttl "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/ttl.py"
click node_config "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/config.py"
click node_metrics "https://github.com/gkavinrajancodes/pulsedb/blob/main/server/main.py"

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_syncsdk,node_asyncsdk,node_langchain,node_developer toneBlue
class node_httpapi,node_tcp,node_resp,node_protocol,node_rediscli toneAmber
class node_router,node_cluster,node_external_llm toneMint
class node_kv,node_types,node_vectors,node_pubsub,node_sleep toneRose
class node_persistence,node_ttl,node_config,node_metrics toneIndigo
```

## Components

### Client Interfaces

- [Python SDK](https://github.com/gkavinrajancodes/pulsedb/blob/main/sdk/pulsedb/client.py): `sdk/pulsedb/client.py`
- [Async SDK](https://github.com/gkavinrajancodes/pulsedb/blob/main/sdk/pulsedb/async_client.py): `sdk/pulsedb/async_client.py`
- [LangChain Store](https://github.com/gkavinrajancodes/pulsedb/blob/main/sdk/langchain_pulsedb/vectorstore.py): `sdk/langchain_pulsedb/vectorstore.py`

### Server Entry Points

- [HTTP Gateway](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/main.py): `server/main.py`
- [RESP2 TCP Server](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/tcp_server.py): `server/tcp_server.py`
- [RESP Encoder](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/resp.py): `server/resp.py`
- [Binary Protocol](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/protocol.py): `server/protocol.py`

### Command Processing

- [Command Executor](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/commands.py): `server/commands.py`
- [Cluster Routing](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/cluster.py): `server/cluster.py`

### Data Engines

- [Sharded KV Store](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/store.py): `server/store.py`
- [Lists and Hashes](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/data_types.py): `server/data_types.py`
- [HNSW Vector Engine](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/vector.py): `server/vector.py`
- [Pub/Sub](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/pubsub.py): `server/pubsub.py`
- [Memory Consolidation](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/sleep_engine.py): `server/sleep_engine.py`

### Operations

- [WAL and Snapshots](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/persistence.py): `server/persistence.py`
- [TTL Sweeper](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/ttl.py): `server/ttl.py`
- [Server Configuration](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/config.py): `server/config.py`
- [Health and Metrics](https://github.com/gkavinrajancodes/pulsedb/blob/main/server/main.py): `server/main.py`

### Other components

- **Application / Client**
- **Redis-compatible Client**
- **OpenAI API**

## Connections

- Application / Client → Python SDK: uses (evidence: `README.md`)
- Application / Client → Async SDK: uses (evidence: `README.md`)
- Application / Client → LangChain Store: ingests and searches (evidence: `README.md`)
- Python SDK → Async SDK: delegates (evidence: `sdk/pulsedb/client.py`)
- Async SDK → RESP2 TCP Server: sends commands (evidence: `README.md`)
- LangChain Store → Python SDK: uses SDK (evidence: `README.md`)
- Redis-compatible Client → RESP2 TCP Server: sends RESP2 (evidence: `README.md`)
- Application / Client → HTTP Gateway: sends HTTP commands (evidence: `README.md`)
- HTTP Gateway → Command Executor: executes commands (evidence: `server/main.py`)
- RESP2 TCP Server → RESP Encoder: encodes RESP (evidence: `server/tcp_server.py`)
- RESP2 TCP Server → Binary Protocol: decodes binary protocol (evidence: `server/tcp_server.py`)
- RESP2 TCP Server → Command Executor: dispatches commands (evidence: `server/tcp_server.py`)
- Command Executor → Sharded KV Store: reads and writes (evidence: `server/commands.py`)
- Command Executor → Lists and Hashes: dispatches type commands (evidence: `server/commands.py`)
- Command Executor → HNSW Vector Engine: dispatches vector commands (evidence: `server/commands.py`)
- Command Executor → Pub/Sub: publishes messages (evidence: `server/commands.py`)
- Command Executor → WAL and Snapshots: logs writes (evidence: `server/commands.py`)
- Command Executor → Cluster Routing: routes commands (evidence: `server/commands.py`)
- Command Executor → Memory Consolidation: runs consolidation (evidence: `server/commands.py`)
- TTL Sweeper → Sharded KV Store: expires keys (evidence: `server/ttl.py`)
- HTTP Gateway → Pub/Sub: streams subscriptions (evidence: `server/main.py`)
- WAL and Snapshots → Sharded KV Store: recovers and snapshots (evidence: `server/persistence.py`)
- HNSW Vector Engine → WAL and Snapshots: saves graph snapshots (evidence: `README.md`)
- RESP2 TCP Server → Server Configuration: loads auth and TLS settings (evidence: `server/tcp_server.py`)
- HTTP Gateway → Server Configuration: checks API key (evidence: `README.md`)
- HTTP Gateway → Health and Metrics: exposes health and metrics (evidence: `README.md`)
- Memory Consolidation → HNSW Vector Engine: consolidates memories (evidence: `server/sleep_engine.py`)
- Memory Consolidation → OpenAI API: summarizes with (evidence: `server/sleep_engine.py`)