# tribrix23/cleavedb architecture

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

- Interactive diagram: https://gitdiagram.com/tribrix23/cleavedb
- Repository: https://github.com/tribrix23/cleavedb

## Overview

CleaveDB is a document database that combines CleaveQL querying, bonds for connected data, and semantic search. The primary workflow is a client sending a query to the server, which parses and executes it; storage and search capabilities supply the database operations. The graph includes documented product stages and sampled storage layers. Some engine subsystems are represented by their exact enclosing directory because their implementations were not excerpted; relationships not established by the excerpts, source index, or README are omitted.

Main entry points: [`cleaveql/interpreter.py`](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/interpreter.py) (Query Interpreter), [`cleavedb_server.py`](https://github.com/tribrix23/cleavedb/blob/main/cleavedb_server.py) (TCP Server), [`cleaveql/parser.py`](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/parser.py) (Query Parser), [`storage/src/python.rs`](https://github.com/tribrix23/cleavedb/blob/main/storage/src/python.rs) (Python Binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client and Server"]
  node_client["Database Client<br/>[cleave_cli.py]"]
  node_server["TCP Server<br/>[cleavedb_server.py]"]
end

subgraph group_query["CleaveQL"]
  node_lexer["Query Lexer<br/>[lexer.py]"]
  node_tokens["Query Tokens<br/>[tokens.py]"]
  node_parser["Query Parser<br/>[parser.py]"]
  node_ast["Query AST<br/>[ast.py]"]
  node_interpreter["Query Interpreter<br/>[interpreter.py]"]
  node_planner["Query Planning<br/>[planner.py]"]
  node_security["Query Security<br/>[security.py]"]
end

subgraph group_engine["Database Engine"]
  node_binding["Python Binding<br/>[python.rs]"]
  node_database["Database Operations<br/>[operations.rs]"]
  node_documents["Documents and Bonds"]
  node_indexes["Indexes and Shards"]
  node_executor["Query Executors<br/>[volcano.rs]"]
  node_btree[("B+ Tree<br/>[mod.rs]")]
  node_buffer["Buffer Pool<br/>[buffer_pool.rs]"]
  node_pages["Storage Pages<br/>[page.rs]"]
  node_wal[("Write-Ahead Log<br/>[wal.rs]")]
end

subgraph group_search["Semantic Search"]
  node_semantic["Semantic Search<br/>[sra.py]"]
  node_vectors[("Vector Index<br/>[vector_index.rs]")]
end

node_user(("User"))
node_client_actor(("External Client"))

node_user -->|"issues queries"| node_client
node_client -.->|"sends requests"| node_server
node_server -->|"tokenizes"| node_lexer
node_server -->|"parses"| node_parser
node_server -->|"executes"| node_interpreter
node_lexer -->|"uses"| node_tokens
node_parser -->|"consumes"| node_tokens
node_parser -->|"builds"| node_ast
node_interpreter -->|"uses"| node_security
node_interpreter -->|"uses"| node_semantic
node_interpreter -.->|"plans queries"| node_planner
node_interpreter -.->|"calls storage"| node_binding
node_binding -->|"accesses"| node_database
node_database -.->|"manages"| node_documents
node_database -.->|"uses"| node_indexes
node_executor -->|"processes"| node_documents
node_binding -->|"uses"| node_btree
node_btree -->|"fetches pages"| node_buffer
node_buffer -->|"loads and flushes"| node_pages
node_btree -->|"logs mutations"| node_wal
node_semantic -.->|"searches vectors"| node_vectors
node_client_actor -.->|"connects"| node_server

click node_client "https://github.com/tribrix23/cleavedb/blob/main/cleave_cli.py"
click node_server "https://github.com/tribrix23/cleavedb/blob/main/cleavedb_server.py"
click node_lexer "https://github.com/tribrix23/cleavedb/blob/main/cleaveql/lexer.py"
click node_tokens "https://github.com/tribrix23/cleavedb/blob/main/cleaveql/tokens.py"
click node_parser "https://github.com/tribrix23/cleavedb/blob/main/cleaveql/parser.py"
click node_ast "https://github.com/tribrix23/cleavedb/blob/main/cleaveql/ast.py"
click node_interpreter "https://github.com/tribrix23/cleavedb/blob/main/cleaveql/interpreter.py"
click node_planner "https://github.com/tribrix23/cleavedb/blob/main/cleaveql/planner.py"
click node_security "https://github.com/tribrix23/cleavedb/blob/main/cleaveql/security.py"
click node_binding "https://github.com/tribrix23/cleavedb/blob/main/storage/src/python.rs"
click node_database "https://github.com/tribrix23/cleavedb/blob/main/storage/src/engine/operations.rs"
click node_documents "https://github.com/tribrix23/cleavedb/tree/main/storage/src/engine"
click node_indexes "https://github.com/tribrix23/cleavedb/tree/main/storage/src/engine"
click node_executor "https://github.com/tribrix23/cleavedb/blob/main/storage/src/engine/volcano.rs"
click node_btree "https://github.com/tribrix23/cleavedb/blob/main/storage/src/btree/mod.rs"
click node_buffer "https://github.com/tribrix23/cleavedb/blob/main/storage/src/buffer_pool.rs"
click node_pages "https://github.com/tribrix23/cleavedb/blob/main/storage/src/page.rs"
click node_wal "https://github.com/tribrix23/cleavedb/blob/main/storage/src/wal.rs"
click node_semantic "https://github.com/tribrix23/cleavedb/blob/main/attention/sra.py"
click node_vectors "https://github.com/tribrix23/cleavedb/blob/main/storage/src/engine/vector_index.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_client,node_server,node_user,node_client_actor toneBlue
class node_lexer,node_tokens,node_parser,node_ast,node_interpreter,node_planner,node_security toneAmber
class node_binding,node_database,node_documents,node_indexes,node_executor,node_btree,node_buffer,node_pages,node_wal toneMint
class node_semantic,node_vectors toneRose
```

## Components

### Client and Server

- [Database Client](https://github.com/tribrix23/cleavedb/blob/main/cleave_cli.py): `cleave_cli.py`
- [TCP Server](https://github.com/tribrix23/cleavedb/blob/main/cleavedb_server.py): `cleavedb_server.py`

### CleaveQL

- [Query Lexer](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/lexer.py): `cleaveql/lexer.py`
- [Query Tokens](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/tokens.py): `cleaveql/tokens.py`
- [Query Parser](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/parser.py): `cleaveql/parser.py`
- [Query AST](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/ast.py): `cleaveql/ast.py`
- [Query Interpreter](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/interpreter.py): `cleaveql/interpreter.py`
- [Query Planning](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/planner.py): `cleaveql/planner.py`
- [Query Security](https://github.com/tribrix23/cleavedb/blob/main/cleaveql/security.py): `cleaveql/security.py`

### Database Engine

- [Python Binding](https://github.com/tribrix23/cleavedb/blob/main/storage/src/python.rs): `storage/src/python.rs`
- [Database Operations](https://github.com/tribrix23/cleavedb/blob/main/storage/src/engine/operations.rs): `storage/src/engine/operations.rs`
- [Documents and Bonds](https://github.com/tribrix23/cleavedb/tree/main/storage/src/engine): `storage/src/engine`
- [Indexes and Shards](https://github.com/tribrix23/cleavedb/tree/main/storage/src/engine): `storage/src/engine`
- [Query Executors](https://github.com/tribrix23/cleavedb/blob/main/storage/src/engine/volcano.rs): `storage/src/engine/volcano.rs`
- [B+ Tree](https://github.com/tribrix23/cleavedb/blob/main/storage/src/btree/mod.rs): `storage/src/btree/mod.rs`
- [Buffer Pool](https://github.com/tribrix23/cleavedb/blob/main/storage/src/buffer_pool.rs): `storage/src/buffer_pool.rs`
- [Storage Pages](https://github.com/tribrix23/cleavedb/blob/main/storage/src/page.rs): `storage/src/page.rs`
- [Write-Ahead Log](https://github.com/tribrix23/cleavedb/blob/main/storage/src/wal.rs): `storage/src/wal.rs`

### Semantic Search

- [Semantic Search](https://github.com/tribrix23/cleavedb/blob/main/attention/sra.py): `attention/sra.py`
- [Vector Index](https://github.com/tribrix23/cleavedb/blob/main/storage/src/engine/vector_index.rs): `storage/src/engine/vector_index.rs`

### Other components

- **User**
- **External Client**

## Connections

- User → Database Client: issues queries
- Database Client → TCP Server: sends requests (evidence: `cleave_cli.py`)
- TCP Server → Query Lexer: tokenizes (evidence: `cleavedb_server.py`)
- TCP Server → Query Parser: parses (evidence: `cleavedb_server.py`)
- TCP Server → Query Interpreter: executes (evidence: `cleavedb_server.py`)
- Query Lexer → Query Tokens: uses (evidence: `cleaveql/lexer.py`)
- Query Parser → Query Tokens: consumes (evidence: `cleaveql/parser.py`)
- Query Parser → Query AST: builds (evidence: `cleaveql/parser.py`)
- Query Interpreter → Query Security: uses (evidence: `cleaveql/interpreter.py`)
- Query Interpreter → Semantic Search: uses (evidence: `cleaveql/interpreter.py`)
- Query Interpreter → Query Planning: plans queries
- Query Interpreter → Python Binding: calls storage
- Python Binding → Database Operations: accesses (evidence: `storage/src/python.rs`)
- Database Operations → Documents and Bonds: manages (evidence: `storage/src/engine/mod.rs`)
- Database Operations → Indexes and Shards: uses (evidence: `storage/src/engine/mod.rs`)
- Query Executors → Documents and Bonds: processes (evidence: `storage/src/engine/volcano.rs`)
- Python Binding → B+ Tree: uses (evidence: `storage/src/python.rs`)
- B+ Tree → Buffer Pool: fetches pages (evidence: `storage/src/btree/mod.rs`)
- Buffer Pool → Storage Pages: loads and flushes (evidence: `storage/src/buffer_pool.rs`)
- B+ Tree → Write-Ahead Log: logs mutations (evidence: `storage/src/btree/mod.rs`)
- Semantic Search → Vector Index: searches vectors
- External Client → TCP Server: connects