# helixdb/helix-db architecture

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

- Interactive diagram: https://gitdiagram.com/helixdb/helix-db
- Repository: https://github.com/helixdb/helix-db

## Overview

HelixDB is a graph database with transactional graph queries, vector search, and BM25 full-text search. A typical workflow is to build a query with an SDK or CLI, send it to a running instance, execute it through the query service and interpreter, and receive results. The planner and index lifecycle provide important internal layers. Relationships below are limited to README statements and sampled-source references; unsampled subsystem connections are omitted.

Main entry points: [`crates/db/src/query_service.rs`](https://github.com/helixdb/helix-db/blob/main/crates/db/src/query_service.rs) (Query Service), [`crates/db/src/execution/interpreter/mod.rs`](https://github.com/helixdb/helix-db/blob/main/crates/db/src/execution/interpreter/mod.rs) (Query Interpreter), [`crates/planner/src/relational/pipeline.rs`](https://github.com/helixdb/helix-db/blob/main/crates/planner/src/relational/pipeline.rs) (Query Planner), [`crates/db/src/index_lifecycle/mod.rs`](https://github.com/helixdb/helix-db/blob/main/crates/db/src/index_lifecycle/mod.rs) (Index Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and CLI"]
  node_sdk["Language SDKs"]
  node_cli["Helix CLI<br/>[query.rs]"]
end

subgraph group_service["Service Boundary"]
  node_server["Database Server<br/>[main.rs]"]
  node_query_service["Query Service<br/>[query_service.rs]"]
end

subgraph group_query["Query Runtime"]
  node_planner["Query Planner<br/>[pipeline.rs]"]
  node_logical_pipeline["Logical Pipelines<br/>[pipeline.rs]"]
  node_physical_plan["Physical Plan<br/>[pipeline.rs]"]
  node_interpreter["Query Interpreter<br/>[mod.rs]"]
end

subgraph group_storage["Storage and Search"]
  node_storage_access["Storage Access<br/>[storage.rs]"]
  node_encoding["Graph Encoding<br/>[mod.rs]"]
  node_graph_data[("Transactional Graph Data")]
  node_vector_search["Vector Search"]
  node_text_search["BM25 Text Search"]
end

subgraph group_lifecycle["Index Lifecycle"]
  node_index_lifecycle["Index Lifecycle<br/>[mod.rs]"]
  node_index_queue["Index Operation Queue"]
end

node_developer(("Application Developer"))
node_object_storage[("Object Storage")]

node_developer -->|"builds queries"| node_sdk
node_developer -->|"runs commands"| node_cli
node_sdk -->|"sends requests"| node_server
node_cli -->|"queries instance"| node_server
node_server -.->|"handles queries"| node_query_service
node_query_service -->|"executes queries"| node_interpreter
node_query_service -.->|"plans requests"| node_planner
node_query_service -->|"supports Cypher"| node_planner
node_planner -->|"uses logical operators"| node_logical_pipeline
node_planner -->|"selects physical strategies"| node_physical_plan
node_interpreter -->|"reads and writes"| node_storage_access
node_storage_access -->|"uses encoded keys"| node_encoding
node_interpreter -.->|"supports vector queries"| node_vector_search
node_interpreter -.->|"supports text queries"| node_text_search
node_index_lifecycle -->|"manages operations"| node_index_queue
node_index_queue -.->|"persists queue data"| node_object_storage
node_index_lifecycle -.->|"maintains search indexes"| node_vector_search
node_index_lifecycle -.->|"maintains search indexes"| node_text_search
node_storage_access -.->|"accesses records"| node_graph_data

click node_sdk "https://github.com/helixdb/helix-db/tree/main/sdks"
click node_cli "https://github.com/helixdb/helix-db/blob/main/crates/cli/src/commands/query.rs"
click node_server "https://github.com/helixdb/helix-db/blob/main/crates/server/src/main.rs"
click node_query_service "https://github.com/helixdb/helix-db/blob/main/crates/db/src/query_service.rs"
click node_planner "https://github.com/helixdb/helix-db/blob/main/crates/planner/src/relational/pipeline.rs"
click node_logical_pipeline "https://github.com/helixdb/helix-db/blob/main/crates/planner/src/logical/access/pipeline.rs"
click node_physical_plan "https://github.com/helixdb/helix-db/blob/main/crates/planner/src/physical/pipeline.rs"
click node_interpreter "https://github.com/helixdb/helix-db/blob/main/crates/db/src/execution/interpreter/mod.rs"
click node_storage_access "https://github.com/helixdb/helix-db/blob/main/crates/db/src/execution/interpreter/storage.rs"
click node_encoding "https://github.com/helixdb/helix-db/blob/main/crates/db/src/encoding/mod.rs"
click node_graph_data "https://github.com/helixdb/helix-db/tree/main/crates/db/src"
click node_vector_search "https://github.com/helixdb/helix-db/tree/main/crates/db/src/search/vector"
click node_text_search "https://github.com/helixdb/helix-db/tree/main/crates/db/src/search/text"
click node_index_lifecycle "https://github.com/helixdb/helix-db/blob/main/crates/db/src/index_lifecycle/mod.rs"
click node_index_queue "https://github.com/helixdb/helix-db/tree/main/crates/db/src/index_lifecycle/queue"

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_sdk,node_cli toneBlue
class node_server,node_query_service,node_object_storage toneAmber
class node_planner,node_logical_pipeline,node_physical_plan,node_interpreter toneMint
class node_storage_access,node_encoding,node_graph_data,node_vector_search,node_text_search toneRose
class node_index_lifecycle,node_index_queue,node_developer toneIndigo
```

## Components

### Clients and CLI

- [Language SDKs](https://github.com/helixdb/helix-db/tree/main/sdks): `sdks`
- [Helix CLI](https://github.com/helixdb/helix-db/blob/main/crates/cli/src/commands/query.rs): `crates/cli/src/commands/query.rs`

### Service Boundary

- [Database Server](https://github.com/helixdb/helix-db/blob/main/crates/server/src/main.rs): `crates/server/src/main.rs`
- [Query Service](https://github.com/helixdb/helix-db/blob/main/crates/db/src/query_service.rs): `crates/db/src/query_service.rs`

### Query Runtime

- [Query Planner](https://github.com/helixdb/helix-db/blob/main/crates/planner/src/relational/pipeline.rs): `crates/planner/src/relational/pipeline.rs`
- [Logical Pipelines](https://github.com/helixdb/helix-db/blob/main/crates/planner/src/logical/access/pipeline.rs): `crates/planner/src/logical/access/pipeline.rs`
- [Physical Plan](https://github.com/helixdb/helix-db/blob/main/crates/planner/src/physical/pipeline.rs): `crates/planner/src/physical/pipeline.rs`
- [Query Interpreter](https://github.com/helixdb/helix-db/blob/main/crates/db/src/execution/interpreter/mod.rs): `crates/db/src/execution/interpreter/mod.rs`

### Storage and Search

- [Storage Access](https://github.com/helixdb/helix-db/blob/main/crates/db/src/execution/interpreter/storage.rs): `crates/db/src/execution/interpreter/storage.rs`
- [Graph Encoding](https://github.com/helixdb/helix-db/blob/main/crates/db/src/encoding/mod.rs): `crates/db/src/encoding/mod.rs`
- [Transactional Graph Data](https://github.com/helixdb/helix-db/tree/main/crates/db/src): `crates/db/src`
- [Vector Search](https://github.com/helixdb/helix-db/tree/main/crates/db/src/search/vector): `crates/db/src/search/vector`
- [BM25 Text Search](https://github.com/helixdb/helix-db/tree/main/crates/db/src/search/text): `crates/db/src/search/text`

### Index Lifecycle

- [Index Lifecycle](https://github.com/helixdb/helix-db/blob/main/crates/db/src/index_lifecycle/mod.rs): `crates/db/src/index_lifecycle/mod.rs`
- [Index Operation Queue](https://github.com/helixdb/helix-db/tree/main/crates/db/src/index_lifecycle/queue): `crates/db/src/index_lifecycle/queue`

### Other components

- **Application Developer**
- **Object Storage**

## Connections

- Application Developer → Language SDKs: builds queries (evidence: `README.md`)
- Application Developer → Helix CLI: runs commands (evidence: `README.md`)
- Language SDKs → Database Server: sends requests (evidence: `README.md`)
- Helix CLI → Database Server: queries instance (evidence: `README.md`)
- Database Server → Query Service: handles queries
- Query Service → Query Interpreter: executes queries (evidence: `crates/db/src/query_service.rs`)
- Query Service → Query Planner: plans requests
- Query Service → Query Planner: supports Cypher (evidence: `crates/db/src/query_service.rs`)
- Query Planner → Logical Pipelines: uses logical operators (evidence: `crates/planner/src/relational/pipeline.rs`)
- Query Planner → Physical Plan: selects physical strategies (evidence: `crates/planner/src/relational/pipeline.rs`)
- Query Interpreter → Storage Access: reads and writes (evidence: `crates/db/src/execution/interpreter/storage.rs`)
- Storage Access → Graph Encoding: uses encoded keys (evidence: `crates/db/src/execution/interpreter/storage.rs`)
- Query Interpreter → Vector Search: supports vector queries (evidence: `crates/db/src/execution/interpreter/mod.rs`)
- Query Interpreter → BM25 Text Search: supports text queries
- Index Lifecycle → Index Operation Queue: manages operations (evidence: `crates/db/src/index_lifecycle/mod.rs`)
- Index Operation Queue → Object Storage: persists queue data
- Index Lifecycle → Vector Search: maintains search indexes
- Index Lifecycle → BM25 Text Search: maintains search indexes
- Storage Access → Transactional Graph Data: accesses records (evidence: `crates/db/src/execution/interpreter/storage.rs`)
