# tapiruslab/tapirusdb architecture

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

- Interactive diagram: https://gitdiagram.com/tapiruslab/tapirusdb
- Repository: https://github.com/tapiruslab/tapirusdb

## Overview

TapirusDB is an embedded multi-model database and AI memory engine. Its main workflow is an application using the Rust API to execute database operations and receive results; SQL operations pass through query processing to execution and persistent page storage, while graph, vector, document, and memory capabilities provide distinct data and retrieval stages. The README documents MCP and remote page streaming; source excerpts were limited, so their internal wiring is not inferred.

Main entry points: [`src/lib.rs`](https://github.com/tapiruslab/tapirusdb/blob/main/src/lib.rs) (Rust API), [`src/sql/mod.rs`](https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/mod.rs) (SQL Engine), [`src/pager/mod.rs`](https://github.com/tapiruslab/tapirusdb/blob/main/src/pager/mod.rs) (Page Storage), [`src/sql/executor.rs`](https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/executor.rs) (SQL Executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application Interfaces"]
  node_api["Rust API<br/>[lib.rs]"]
  node_cli["CLI and MCP<br/>[tapirus.rs]"]
end

subgraph group_query["SQL Engine"]
  node_lexer["SQL Lexer<br/>[lexer.rs]"]
  node_parser["SQL Parser<br/>[parser.rs]"]
  node_planner["SQL Planner<br/>[planner.rs]"]
  node_executor["SQL Executor<br/>[executor.rs]"]
  node_sql["SQL Engine<br/>[mod.rs]"]
end

subgraph group_models["Data Models"]
  node_documents["JSON Documents<br/>[mod.rs]"]
  node_vectors["Vector Search<br/>[mod.rs]"]
  node_graph["Property Graph<br/>[mod.rs]"]
  node_graphrag["GraphRAG<br/>[rag.rs]"]
  node_memory["Agent Memory<br/>[mod.rs]"]
  node_realtime["Change Events<br/>[mod.rs]"]
end

subgraph group_storage["Storage and Security"]
  node_btree["B+Tree<br/>[engine.rs]"]
  node_pager["Page Storage<br/>[mod.rs]"]
  node_wal["Write-Ahead Log<br/>[wal.rs]"]
  node_remote["Remote Pages<br/>[remote.rs]"]
  node_crypto["Page Encryption<br/>[mod.rs]"]
end

node_application(("Application"))

node_application -->|"calls"| node_api
node_application -->|"invokes"| node_cli
node_api -->|"executes SQL"| node_sql
node_sql -->|"tokenizes"| node_lexer
node_sql -->|"parses"| node_parser
node_sql -->|"plans"| node_planner
node_sql -->|"executes"| node_executor
node_executor -->|"reads and writes"| node_pager
node_pager -->|"stores records"| node_btree
node_pager -->|"appends frames"| node_wal
node_pager -->|"encrypts pages"| node_crypto
node_pager -.->|"streams ranges"| node_remote
node_api -->|"manages graph"| node_graph
node_api -->|"manages memories"| node_memory
node_api -->|"publishes changes"| node_realtime
node_documents -->|"uses connection"| node_api
node_memory -->|"scores vectors"| node_vectors
node_graphrag -->|"traverses graph"| node_graph

click node_api "https://github.com/tapiruslab/tapirusdb/blob/main/src/lib.rs"
click node_cli "https://github.com/tapiruslab/tapirusdb/blob/main/src/bin/tapirus.rs"
click node_lexer "https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/lexer.rs"
click node_parser "https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/parser.rs"
click node_planner "https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/planner.rs"
click node_executor "https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/executor.rs"
click node_sql "https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/mod.rs"
click node_documents "https://github.com/tapiruslab/tapirusdb/blob/main/src/document/mod.rs"
click node_vectors "https://github.com/tapiruslab/tapirusdb/blob/main/src/vector/mod.rs"
click node_graph "https://github.com/tapiruslab/tapirusdb/blob/main/src/graph/mod.rs"
click node_graphrag "https://github.com/tapiruslab/tapirusdb/blob/main/src/graph/rag.rs"
click node_memory "https://github.com/tapiruslab/tapirusdb/blob/main/src/memory/mod.rs"
click node_realtime "https://github.com/tapiruslab/tapirusdb/blob/main/src/realtime/mod.rs"
click node_btree "https://github.com/tapiruslab/tapirusdb/blob/main/src/btree/engine.rs"
click node_pager "https://github.com/tapiruslab/tapirusdb/blob/main/src/pager/mod.rs"
click node_wal "https://github.com/tapiruslab/tapirusdb/blob/main/src/pager/wal.rs"
click node_remote "https://github.com/tapiruslab/tapirusdb/blob/main/src/pager/remote.rs"
click node_crypto "https://github.com/tapiruslab/tapirusdb/blob/main/src/crypto/mod.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_api,node_cli toneBlue
class node_lexer,node_parser,node_planner,node_executor,node_sql toneAmber
class node_documents,node_vectors,node_graph,node_graphrag,node_memory,node_realtime toneMint
class node_btree,node_pager,node_wal,node_remote,node_crypto toneRose
class node_application toneIndigo
```

## Components

### Application Interfaces

- [Rust API](https://github.com/tapiruslab/tapirusdb/blob/main/src/lib.rs): `src/lib.rs`
- [CLI and MCP](https://github.com/tapiruslab/tapirusdb/blob/main/src/bin/tapirus.rs): `src/bin/tapirus.rs`

### SQL Engine

- [SQL Lexer](https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/lexer.rs): `src/sql/lexer.rs`
- [SQL Parser](https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/parser.rs): `src/sql/parser.rs`
- [SQL Planner](https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/planner.rs): `src/sql/planner.rs`
- [SQL Executor](https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/executor.rs): `src/sql/executor.rs`
- [SQL Engine](https://github.com/tapiruslab/tapirusdb/blob/main/src/sql/mod.rs): `src/sql/mod.rs`

### Data Models

- [JSON Documents](https://github.com/tapiruslab/tapirusdb/blob/main/src/document/mod.rs): `src/document/mod.rs`
- [Vector Search](https://github.com/tapiruslab/tapirusdb/blob/main/src/vector/mod.rs): `src/vector/mod.rs`
- [Property Graph](https://github.com/tapiruslab/tapirusdb/blob/main/src/graph/mod.rs): `src/graph/mod.rs`
- [GraphRAG](https://github.com/tapiruslab/tapirusdb/blob/main/src/graph/rag.rs): `src/graph/rag.rs`
- [Agent Memory](https://github.com/tapiruslab/tapirusdb/blob/main/src/memory/mod.rs): `src/memory/mod.rs`
- [Change Events](https://github.com/tapiruslab/tapirusdb/blob/main/src/realtime/mod.rs): `src/realtime/mod.rs`

### Storage and Security

- [B+Tree](https://github.com/tapiruslab/tapirusdb/blob/main/src/btree/engine.rs): `src/btree/engine.rs`
- [Page Storage](https://github.com/tapiruslab/tapirusdb/blob/main/src/pager/mod.rs): `src/pager/mod.rs`
- [Write-Ahead Log](https://github.com/tapiruslab/tapirusdb/blob/main/src/pager/wal.rs): `src/pager/wal.rs`
- [Remote Pages](https://github.com/tapiruslab/tapirusdb/blob/main/src/pager/remote.rs): `src/pager/remote.rs`
- [Page Encryption](https://github.com/tapiruslab/tapirusdb/blob/main/src/crypto/mod.rs): `src/crypto/mod.rs`

### Other components

- **Application**

## Connections

- Application → Rust API: calls
- Application → CLI and MCP: invokes
- Rust API → SQL Engine: executes SQL
- SQL Engine → SQL Lexer: tokenizes
- SQL Engine → SQL Parser: parses
- SQL Engine → SQL Planner: plans
- SQL Engine → SQL Executor: executes
- SQL Executor → Page Storage: reads and writes
- Page Storage → B+Tree: stores records
- Page Storage → Write-Ahead Log: appends frames
- Page Storage → Page Encryption: encrypts pages
- Page Storage → Remote Pages: streams ranges
- Rust API → Property Graph: manages graph
- Rust API → Agent Memory: manages memories
- Rust API → Change Events: publishes changes
- JSON Documents → Rust API: uses connection
- Agent Memory → Vector Search: scores vectors
- GraphRAG → Property Graph: traverses graph