# luo-yangsiqi/seekdb architecture

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

- Interactive diagram: https://gitdiagram.com/luo-yangsiqi/seekdb
- Repository: https://github.com/luo-yangsiqi/seekdb

## Overview

seekdb is a MySQL-compatible database for agent state, usable embedded or as a server. The principal workflow is a client issuing SQL to write or search state: SQL execution reaches transactional storage, while vector indexing can proceed asynchronously; searches combine vector, full-text, and scalar predicates in one query. The README also documents database forks and merges for copy-on-write exploration. The graph reflects those documented capabilities and the sampled Rust protocol, storage, vector-build, and log code; several product subsystems are documented but their wiring is not visible in the sampled source.

Main entry points: [`src/sql/code_generator/ob_static_engine_cg.cpp`](https://github.com/luo-yangsiqi/seekdb/blob/master/src/sql/code_generator/ob_static_engine_cg.cpp) (SQL execution plans), [`src/data_plane/api/data_plane/access/ob_dml_execution.h`](https://github.com/luo-yangsiqi/seekdb/blob/master/src/data_plane/api/data_plane/access/ob_dml_execution.h) (DML and transactions), [`src/logservice/ob_log_service.cpp`](https://github.com/luo-yangsiqi/seekdb/blob/master/src/logservice/ob_log_service.cpp) (Redo log), [`src/storage/memtable/mvcc/ob_query_engine.cpp`](https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/memtable/mvcc/ob_query_engine.cpp) (MVCC memtable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Client interface"]
  node_nio["MySQL protocol<br/>[lib.rs]"]
end

subgraph group_query["SQL and search"]
  node_sqlgen["SQL execution plans"]
  node_tablet_scan["Tablet scans<br/>[ob_tablet_scan.cpp]"]
  node_vector_search["Vector search"]
  node_fulltext["Full-text search<br/>[ob_fts_parser.h]"]
  node_embedding["Embedding requests"]
end

subgraph group_storage["Transactional storage"]
  node_dml["DML and transactions<br/>[ob_dml_execution.h]"]
  node_memtable["MVCC memtable"]
  node_tablet_meta[("Tablet metadata")]
  node_fork_merge["COW fork and merge"]
end

subgraph group_indexing["Indexing and recovery"]
  node_redo["Redo log<br/>[ob_log_service.cpp]"]
  node_log_engine["Log engine<br/>[log_engine.cpp]"]
  node_change_stream["Change Stream"]
  node_vector_build["Vector index build"]
  node_index_state[("Vector indexes")]
  node_recovery["Storage recovery"]
end

node_client(("SQL client"))

node_client -->|"sends SQL"| node_nio
node_nio -->|"dispatches requests"| node_sqlgen
node_sqlgen -->|"plans DML"| node_dml
node_sqlgen -->|"plans scans"| node_tablet_scan
node_sqlgen -->|"plans vector search"| node_vector_search
node_sqlgen -->|"plans text search"| node_fulltext
node_dml -->|"updates rows"| node_memtable
node_dml -->|"commits redo"| node_redo
node_redo -->|"persists logs"| node_log_engine
node_redo -.->|"feeds asynchronously"| node_change_stream
node_change_stream -.->|"updates delta index"| node_vector_build
node_vector_build -->|"builds snapshots"| node_index_state
node_vector_search -->|"queries indexes"| node_index_state
node_tablet_scan -->|"reads rows"| node_memtable
node_memtable -->|"uses tablet metadata"| node_tablet_meta
node_embedding -.->|"returns vectors"| node_client
node_fork_merge -.->|"manages snapshots"| node_tablet_meta
node_recovery -->|"replays metadata"| node_tablet_meta

click node_nio "https://github.com/luo-yangsiqi/seekdb/blob/master/rust/sql-nio/src/lib.rs"
click node_sqlgen "https://github.com/luo-yangsiqi/seekdb/blob/master/src/sql/code_generator/ob_static_engine_cg.cpp"
click node_tablet_scan "https://github.com/luo-yangsiqi/seekdb/blob/master/src/data_plane/ob_tablet_scan.cpp"
click node_vector_search "https://github.com/luo-yangsiqi/seekdb/tree/master/src/observer/vector_index"
click node_fulltext "https://github.com/luo-yangsiqi/seekdb/blob/master/src/data_plane/api/data_plane/fts/ob_fts_parser.h"
click node_embedding "https://github.com/luo-yangsiqi/seekdb/blob/master/src/query/vector/ob_vector_embedding_handler.cpp"
click node_dml "https://github.com/luo-yangsiqi/seekdb/blob/master/src/data_plane/api/data_plane/access/ob_dml_execution.h"
click node_memtable "https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/memtable/mvcc/ob_query_engine.cpp"
click node_tablet_meta "https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/meta_mem/ob_storage_meta_mem_mgr.cpp"
click node_fork_merge "https://github.com/luo-yangsiqi/seekdb/tree/master/src/storage"
click node_redo "https://github.com/luo-yangsiqi/seekdb/blob/master/src/logservice/ob_log_service.cpp"
click node_log_engine "https://github.com/luo-yangsiqi/seekdb/blob/master/src/logservice/palf/log_engine.cpp"
click node_change_stream "https://github.com/luo-yangsiqi/seekdb/tree/master/src/observer/change_stream"
click node_vector_build "https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/ddl/ob_ddl_pipeline.cpp"
click node_index_state "https://github.com/luo-yangsiqi/seekdb/tree/master/src/observer/vector_index"
click node_recovery "https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/slog_ckpt/ob_local_storage_checkpoint_slog_handler.cpp"

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_nio,node_client toneBlue
class node_sqlgen,node_tablet_scan,node_vector_search,node_fulltext,node_embedding toneAmber
class node_dml,node_memtable,node_tablet_meta,node_fork_merge toneMint
class node_redo,node_log_engine,node_change_stream,node_vector_build,node_index_state,node_recovery toneRose
```

## Components

### Client interface

- [MySQL protocol](https://github.com/luo-yangsiqi/seekdb/blob/master/rust/sql-nio/src/lib.rs): `rust/sql-nio/src/lib.rs`

### SQL and search

- [SQL execution plans](https://github.com/luo-yangsiqi/seekdb/blob/master/src/sql/code_generator/ob_static_engine_cg.cpp): `src/sql/code_generator/ob_static_engine_cg.cpp`
- [Tablet scans](https://github.com/luo-yangsiqi/seekdb/blob/master/src/data_plane/ob_tablet_scan.cpp): `src/data_plane/ob_tablet_scan.cpp`
- [Vector search](https://github.com/luo-yangsiqi/seekdb/tree/master/src/observer/vector_index): `src/observer/vector_index`
- [Full-text search](https://github.com/luo-yangsiqi/seekdb/blob/master/src/data_plane/api/data_plane/fts/ob_fts_parser.h): `src/data_plane/api/data_plane/fts/ob_fts_parser.h`
- [Embedding requests](https://github.com/luo-yangsiqi/seekdb/blob/master/src/query/vector/ob_vector_embedding_handler.cpp): `src/query/vector/ob_vector_embedding_handler.cpp`

### Transactional storage

- [DML and transactions](https://github.com/luo-yangsiqi/seekdb/blob/master/src/data_plane/api/data_plane/access/ob_dml_execution.h): `src/data_plane/api/data_plane/access/ob_dml_execution.h`
- [MVCC memtable](https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/memtable/mvcc/ob_query_engine.cpp): `src/storage/memtable/mvcc/ob_query_engine.cpp`
- [Tablet metadata](https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/meta_mem/ob_storage_meta_mem_mgr.cpp): `src/storage/meta_mem/ob_storage_meta_mem_mgr.cpp`
- [COW fork and merge](https://github.com/luo-yangsiqi/seekdb/tree/master/src/storage): `src/storage`

### Indexing and recovery

- [Redo log](https://github.com/luo-yangsiqi/seekdb/blob/master/src/logservice/ob_log_service.cpp): `src/logservice/ob_log_service.cpp`
- [Log engine](https://github.com/luo-yangsiqi/seekdb/blob/master/src/logservice/palf/log_engine.cpp): `src/logservice/palf/log_engine.cpp`
- [Change Stream](https://github.com/luo-yangsiqi/seekdb/tree/master/src/observer/change_stream): `src/observer/change_stream`
- [Vector index build](https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/ddl/ob_ddl_pipeline.cpp): `src/storage/ddl/ob_ddl_pipeline.cpp`
- [Vector indexes](https://github.com/luo-yangsiqi/seekdb/tree/master/src/observer/vector_index): `src/observer/vector_index`
- [Storage recovery](https://github.com/luo-yangsiqi/seekdb/blob/master/src/storage/slog_ckpt/ob_local_storage_checkpoint_slog_handler.cpp): `src/storage/slog_ckpt/ob_local_storage_checkpoint_slog_handler.cpp`

### Other components

- **SQL client**

## Connections

- SQL client → MySQL protocol: sends SQL
- MySQL protocol → SQL execution plans: dispatches requests
- SQL execution plans → DML and transactions: plans DML
- SQL execution plans → Tablet scans: plans scans
- SQL execution plans → Vector search: plans vector search
- SQL execution plans → Full-text search: plans text search
- DML and transactions → MVCC memtable: updates rows
- DML and transactions → Redo log: commits redo
- Redo log → Log engine: persists logs
- Redo log → Change Stream: feeds asynchronously
- Change Stream → Vector index build: updates delta index
- Vector index build → Vector indexes: builds snapshots
- Vector search → Vector indexes: queries indexes
- Tablet scans → MVCC memtable: reads rows
- MVCC memtable → Tablet metadata: uses tablet metadata
- Embedding requests → SQL client: returns vectors
- COW fork and merge → Tablet metadata: manages snapshots
- Storage recovery → Tablet metadata: replays metadata