# janvencl/graphbuff architecture

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

- Interactive diagram: https://gitdiagram.com/janvencl/graphbuff
- Repository: https://github.com/janvencl/graphbuff

## Overview

GraphBuff is a Rust property-graph database queried with Cypher. Users submit queries through the shell, HTTP/JSON, Bolt, or library API; parsing and planning feed streaming execution, which reads or mutates a selected graph store and returns results. The graph also preserves documented storage modes, administration, security, and GPU acceleration. Some subsystem links are documented only at product level; those are marked dashed rather than inferred from module names.

Main entry points: [`crates/engine/src/plan.rs`](https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/plan.rs) (Query planning), [`crates/server/src/api.rs`](https://github.com/janvencl/graphbuff/blob/main/crates/server/src/api.rs) (HTTP/JSON API), [`crates/core/src/store.rs`](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/store.rs) (Store interface), [`crates/core/src/storage.rs`](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/storage.rs) (Storage selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Interactive shell<br/>[main.rs]"]
  node_bulk_import["CSV import<br/>[import.rs]"]
  node_http_api["HTTP/JSON API<br/>[api.rs]"]
  node_bolt["Bolt protocol<br/>[bolt.rs]"]
end

subgraph group_query["Cypher query engine"]
  node_cypher_parse["Cypher parsing<br/>[parser.rs]"]
  node_query_plan["Query planning<br/>[plan.rs]"]
  node_query_context["Execution context<br/>[context.rs]"]
  node_stream_exec["Streaming execution<br/>[stream.rs]"]
  node_query_result["Query results<br/>[result.rs]"]
end

subgraph group_storage["Graph storage"]
  node_graph_store["Store interface<br/>[store.rs]"]
  node_storage_select["Storage selection<br/>[storage.rs]"]
  node_memory_store[("In-memory graph<br/>[memory.rs]")]
  node_hybrid_store[("Hybrid storage<br/>[hybrid.rs]")]
  node_persistent_store[("Paged storage<br/>[persistent.rs]")]
  node_page_cache[("Page cache and WAL<br/>[pager.rs]")]
end

subgraph group_operations["Admin and security"]
  node_users["Accounts and roles<br/>[users.rs]"]
  node_crypto["Password crypto<br/>[crypto.rs]"]
  node_maintenance["Backup and checks<br/>[maintenance.rs]"]
  node_persistent_maintenance["Persistent maintenance<br/>[maintain.rs]"]
end

subgraph group_acceleration["Acceleration"]
  node_gpu_kernels["GPU kernels<br/>[lib.rs]"]
  node_query_accel["Query acceleration<br/>[accel.rs]"]
end

node_user(("Client or user"))

node_user -->|"runs queries"| node_cli
node_user -->|"sends requests"| node_http_api
node_user -->|"uses drivers"| node_bolt
node_cli -->|"invokes import"| node_bulk_import
node_user -.->|"submits Cypher"| node_cypher_parse
node_http_api -.->|"routes queries"| node_cypher_parse
node_bolt -->|"uses query API"| node_http_api
node_cypher_parse -.->|"builds AST"| node_query_plan
node_query_plan -->|"creates execution"| node_query_context
node_query_plan -->|"builds operators"| node_stream_exec
node_stream_exec -.->|"produces rows"| node_query_result
node_query_context -->|"accesses store"| node_graph_store
node_storage_select -->|"opens mode"| node_memory_store
node_storage_select -->|"opens mode"| node_hybrid_store
node_storage_select -->|"opens mode"| node_persistent_store
node_memory_store -->|"implements"| node_graph_store
node_hybrid_store -->|"implements"| node_graph_store
node_persistent_store -->|"implements"| node_graph_store
node_persistent_store -->|"uses pager"| node_page_cache
node_persistent_maintenance -->|"checks snapshots"| node_page_cache
node_maintenance -->|"supports checks"| node_persistent_maintenance
node_http_api -->|"checks accounts"| node_users
node_users -->|"verifies passwords"| node_crypto
node_query_plan -->|"selects kernels"| node_query_accel
node_query_accel -.->|"dispatches kernels"| node_gpu_kernels

click node_cli "https://github.com/janvencl/graphbuff/blob/main/crates/cli/src/main.rs"
click node_bulk_import "https://github.com/janvencl/graphbuff/blob/main/crates/cli/src/import.rs"
click node_http_api "https://github.com/janvencl/graphbuff/blob/main/crates/server/src/api.rs"
click node_bolt "https://github.com/janvencl/graphbuff/blob/main/crates/server/src/bolt.rs"
click node_users "https://github.com/janvencl/graphbuff/blob/main/crates/server/src/users.rs"
click node_crypto "https://github.com/janvencl/graphbuff/blob/main/crates/server/src/crypto.rs"
click node_cypher_parse "https://github.com/janvencl/graphbuff/blob/main/crates/cypher/src/parser.rs"
click node_query_plan "https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/plan.rs"
click node_query_context "https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/context.rs"
click node_stream_exec "https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/stream.rs"
click node_query_result "https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/result.rs"
click node_graph_store "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/store.rs"
click node_storage_select "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/storage.rs"
click node_memory_store "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/memory.rs"
click node_hybrid_store "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/hybrid.rs"
click node_persistent_store "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/persistent.rs"
click node_page_cache "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/persistent/pager.rs"
click node_maintenance "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/maintenance.rs"
click node_persistent_maintenance "https://github.com/janvencl/graphbuff/blob/main/crates/core/src/persistent/maintain.rs"
click node_gpu_kernels "https://github.com/janvencl/graphbuff/blob/main/crates/gpu/src/lib.rs"
click node_query_accel "https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/accel.rs"

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_cli,node_bulk_import,node_http_api,node_bolt,node_user toneBlue
class node_cypher_parse,node_query_plan,node_query_context,node_stream_exec,node_query_result toneAmber
class node_graph_store,node_storage_select,node_memory_store,node_hybrid_store,node_persistent_store,node_page_cache toneMint
class node_users,node_crypto,node_maintenance,node_persistent_maintenance toneRose
class node_gpu_kernels,node_query_accel toneIndigo
```

## Components

### User interfaces

- [Interactive shell](https://github.com/janvencl/graphbuff/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [CSV import](https://github.com/janvencl/graphbuff/blob/main/crates/cli/src/import.rs): `crates/cli/src/import.rs`
- [HTTP/JSON API](https://github.com/janvencl/graphbuff/blob/main/crates/server/src/api.rs): `crates/server/src/api.rs`
- [Bolt protocol](https://github.com/janvencl/graphbuff/blob/main/crates/server/src/bolt.rs): `crates/server/src/bolt.rs`

### Cypher query engine

- [Cypher parsing](https://github.com/janvencl/graphbuff/blob/main/crates/cypher/src/parser.rs): `crates/cypher/src/parser.rs`
- [Query planning](https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/plan.rs): `crates/engine/src/plan.rs`
- [Execution context](https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/context.rs): `crates/engine/src/context.rs`
- [Streaming execution](https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/stream.rs): `crates/engine/src/stream.rs`
- [Query results](https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/result.rs): `crates/engine/src/result.rs`

### Graph storage

- [Store interface](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/store.rs): `crates/core/src/store.rs`
- [Storage selection](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/storage.rs): `crates/core/src/storage.rs`
- [In-memory graph](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/memory.rs): `crates/core/src/memory.rs`
- [Hybrid storage](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/hybrid.rs): `crates/core/src/hybrid.rs`
- [Paged storage](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/persistent.rs): `crates/core/src/persistent.rs`
- [Page cache and WAL](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/persistent/pager.rs): `crates/core/src/persistent/pager.rs`

### Admin and security

- [Accounts and roles](https://github.com/janvencl/graphbuff/blob/main/crates/server/src/users.rs): `crates/server/src/users.rs`
- [Password crypto](https://github.com/janvencl/graphbuff/blob/main/crates/server/src/crypto.rs): `crates/server/src/crypto.rs`
- [Backup and checks](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/maintenance.rs): `crates/core/src/maintenance.rs`
- [Persistent maintenance](https://github.com/janvencl/graphbuff/blob/main/crates/core/src/persistent/maintain.rs): `crates/core/src/persistent/maintain.rs`

### Acceleration

- [GPU kernels](https://github.com/janvencl/graphbuff/blob/main/crates/gpu/src/lib.rs): `crates/gpu/src/lib.rs`
- [Query acceleration](https://github.com/janvencl/graphbuff/blob/main/crates/engine/src/accel.rs): `crates/engine/src/accel.rs`

### Other components

- **Client or user**

## Connections

- Client or user → Interactive shell: runs queries
- Client or user → HTTP/JSON API: sends requests
- Client or user → Bolt protocol: uses drivers
- Interactive shell → CSV import: invokes import (evidence: `crates/cli/src/main.rs`)
- Client or user → Cypher parsing: submits Cypher
- HTTP/JSON API → Cypher parsing: routes queries
- Bolt protocol → HTTP/JSON API: uses query API (evidence: `crates/server/src/bolt.rs`)
- Cypher parsing → Query planning: builds AST
- Query planning → Execution context: creates execution (evidence: `crates/engine/src/context.rs`)
- Query planning → Streaming execution: builds operators (evidence: `crates/engine/src/plan.rs`)
- Streaming execution → Query results: produces rows
- Execution context → Store interface: accesses store (evidence: `crates/engine/src/context.rs`)
- Storage selection → In-memory graph: opens mode (evidence: `crates/core/src/storage.rs`)
- Storage selection → Hybrid storage: opens mode (evidence: `crates/core/src/storage.rs`)
- Storage selection → Paged storage: opens mode (evidence: `crates/core/src/storage.rs`)
- In-memory graph → Store interface: implements (evidence: `crates/core/src/memory.rs`)
- Hybrid storage → Store interface: implements (evidence: `crates/core/src/hybrid.rs`)
- Paged storage → Store interface: implements (evidence: `crates/core/src/persistent.rs`)
- Paged storage → Page cache and WAL: uses pager (evidence: `crates/core/src/persistent.rs`)
- Persistent maintenance → Page cache and WAL: checks snapshots (evidence: `crates/core/src/persistent/maintain.rs`)
- Backup and checks → Persistent maintenance: supports checks (evidence: `crates/core/src/persistent/maintain.rs`)
- HTTP/JSON API → Accounts and roles: checks accounts (evidence: `crates/server/src/api.rs`)
- Accounts and roles → Password crypto: verifies passwords (evidence: `crates/server/src/users.rs`)
- Query planning → Query acceleration: selects kernels (evidence: `crates/engine/src/plan.rs`)
- Query acceleration → GPU kernels: dispatches kernels