# minhh-nguyen/toydb-pams architecture

> Architecture diagram of the GitHub repository minhh-nguyen/toydb-pams, 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/minhh-nguyen/toydb-pams
- Repository: https://github.com/minhh-nguyen/toydb-pams

## Overview

toyDB is a distributed SQL database with a workload benchmark and experiment-analysis tools. The primary path is a SQL client sending a statement to a server, where a session parses and plans it, executes against transaction/catalog and storage layers, and returns results. Writes are coordinated through Raft replication; the README also documents workload generation and plotting/analysis of experiment data. Some subsystem internals were not sampled, so their detailed calls are omitted rather than inferred.

Main entry points: [`src/server.rs`](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/server.rs) (SQL and Raft server), [`src/sql/execution/session.rs`](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/execution/session.rs) (SQL session), [`src/raft/node.rs`](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/node.rs) (Raft node), [`src/sql/execution/executor.rs`](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/execution/executor.rs) (SQL executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and service"]
  node_sql_client["SQL client<br/>[toysql.rs]"]
  node_server["SQL and Raft server<br/>[server.rs]"]
end

subgraph group_sql["SQL processing"]
  node_session["SQL session<br/>[session.rs]"]
  node_parser["Lexer and parser<br/>[parser.rs]"]
  node_planner["Planner and optimizer<br/>[planner.rs]"]
  node_plans["Execution plans<br/>[plan.rs]"]
  node_executor["SQL executor<br/>[executor.rs]"]
  node_aggregator["Aggregations and joins"]
  node_sql_types["SQL types and schema"]
  node_sql_engine["SQL engine<br/>[engine.rs]"]
end

subgraph group_consensus["Raft consensus"]
  node_raft_node["Raft node<br/>[node.rs]"]
  node_raft_log["Raft log<br/>[log.rs]"]
  node_raft_messages["Raft messages<br/>[message.rs]"]
  node_raft_state["Raft state<br/>[state.rs]"]
end

subgraph group_persistence["Storage and encoding"]
  node_mvcc["MVCC transactions<br/>[mvcc.rs]"]
  node_storage_engine[("Storage engines<br/>[engine.rs]")]
  node_bitcask[("BitCask and memory")]
  node_encoding["Key and value encoding<br/>[keycode.rs]"]
end

subgraph group_analysis["Benchmark analysis"]
  node_workload["Workload benchmark<br/>[workload.rs]"]
  node_plot_config["Experiment data analysis<br/>[config.py]"]
  node_plot_scripts["Experiment charts"]
end

node_operator(("SQL user"))
node_cluster(("Database cluster"))
node_experiment_data["CSV experiment data"]
node_chart_user(("Experiment analyst"))

node_operator -->|"submits SQL"| node_sql_client
node_sql_client -.->|"sends requests"| node_server
node_server -->|"creates session"| node_session
node_session -->|"parses SQL"| node_parser
node_session -->|"builds plan"| node_planner
node_planner -.->|"uses schema"| node_sql_types
node_session -->|"opens transaction"| node_sql_engine
node_sql_engine -.->|"uses MVCC"| node_mvcc
node_plans -->|"executes plan"| node_executor
node_executor -.->|"delegates operators"| node_aggregator
node_executor -.->|"reads and writes"| node_sql_engine
node_server -->|"serves SQL and Raft"| node_cluster
node_server -->|"routes Raft requests"| node_raft_node
node_raft_node -->|"manages log"| node_raft_log
node_raft_node -->|"exchanges messages"| node_raft_messages
node_raft_node -->|"applies state"| node_raft_state
node_raft_log -->|"persists log"| node_storage_engine
node_mvcc -->|"stores versions"| node_storage_engine
node_storage_engine -.->|"implemented by"| node_bitcask
node_mvcc -->|"encodes keys"| node_encoding
node_workload -.->|"benchmarks"| node_cluster
node_cluster -.->|"produces measurements"| node_experiment_data
node_experiment_data -->|"loads CSV"| node_plot_config
node_plot_config -->|"supports charts"| node_plot_scripts
node_chart_user -.->|"generates charts"| node_plot_scripts

click node_sql_client "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/bin/toysql.rs"
click node_server "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/server.rs"
click node_session "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/execution/session.rs"
click node_parser "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/parser/parser.rs"
click node_planner "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/planner/planner.rs"
click node_plans "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/planner/plan.rs"
click node_executor "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/execution/executor.rs"
click node_aggregator "https://github.com/minhh-nguyen/toydb-pams/tree/main/src/sql/execution"
click node_sql_types "https://github.com/minhh-nguyen/toydb-pams/tree/main/src/sql/types"
click node_sql_engine "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/engine/engine.rs"
click node_raft_node "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/node.rs"
click node_raft_log "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/log.rs"
click node_raft_messages "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/message.rs"
click node_raft_state "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/state.rs"
click node_mvcc "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/storage/mvcc.rs"
click node_storage_engine "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/storage/engine.rs"
click node_bitcask "https://github.com/minhh-nguyen/toydb-pams/tree/main/src/storage"
click node_encoding "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/encoding/keycode.rs"
click node_workload "https://github.com/minhh-nguyen/toydb-pams/blob/main/src/bin/workload.rs"
click node_plot_config "https://github.com/minhh-nguyen/toydb-pams/blob/main/plot/config.py"
click node_plot_scripts "https://github.com/minhh-nguyen/toydb-pams/tree/main/plot"

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_sql_client,node_server,node_operator toneBlue
class node_session,node_parser,node_planner,node_plans,node_executor,node_aggregator,node_sql_types,node_sql_engine,node_cluster toneAmber
class node_raft_node,node_raft_log,node_raft_messages,node_raft_state toneMint
class node_mvcc,node_storage_engine,node_bitcask,node_encoding toneRose
class node_workload,node_plot_config,node_plot_scripts,node_experiment_data,node_chart_user toneIndigo
```

## Components

### Clients and service

- [SQL client](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/bin/toysql.rs): `src/bin/toysql.rs`
- [SQL and Raft server](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/server.rs): `src/server.rs`

### SQL processing

- [SQL session](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/execution/session.rs): `src/sql/execution/session.rs`
- [Lexer and parser](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/parser/parser.rs): `src/sql/parser/parser.rs`
- [Planner and optimizer](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/planner/planner.rs): `src/sql/planner/planner.rs`
- [Execution plans](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/planner/plan.rs): `src/sql/planner/plan.rs`
- [SQL executor](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/execution/executor.rs): `src/sql/execution/executor.rs`
- [Aggregations and joins](https://github.com/minhh-nguyen/toydb-pams/tree/main/src/sql/execution): `src/sql/execution`
- [SQL types and schema](https://github.com/minhh-nguyen/toydb-pams/tree/main/src/sql/types): `src/sql/types`
- [SQL engine](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/sql/engine/engine.rs): `src/sql/engine/engine.rs`

### Raft consensus

- [Raft node](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/node.rs): `src/raft/node.rs`
- [Raft log](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/log.rs): `src/raft/log.rs`
- [Raft messages](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/message.rs): `src/raft/message.rs`
- [Raft state](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/raft/state.rs): `src/raft/state.rs`

### Storage and encoding

- [MVCC transactions](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/storage/mvcc.rs): `src/storage/mvcc.rs`
- [Storage engines](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/storage/engine.rs): `src/storage/engine.rs`
- [BitCask and memory](https://github.com/minhh-nguyen/toydb-pams/tree/main/src/storage): `src/storage`
- [Key and value encoding](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/encoding/keycode.rs): `src/encoding/keycode.rs`

### Benchmark analysis

- [Workload benchmark](https://github.com/minhh-nguyen/toydb-pams/blob/main/src/bin/workload.rs): `src/bin/workload.rs`
- [Experiment data analysis](https://github.com/minhh-nguyen/toydb-pams/blob/main/plot/config.py): `plot/config.py`
- [Experiment charts](https://github.com/minhh-nguyen/toydb-pams/tree/main/plot): `plot`

### Other components

- **SQL user**
- **Database cluster**
- **CSV experiment data**
- **Experiment analyst**

## Connections

- SQL user → SQL client: submits SQL
- SQL client → SQL and Raft server: sends requests
- SQL and Raft server → SQL session: creates session
- SQL session → Lexer and parser: parses SQL
- SQL session → Planner and optimizer: builds plan
- Planner and optimizer → SQL types and schema: uses schema
- SQL session → SQL engine: opens transaction (evidence: `src/sql/execution/session.rs`)
- SQL engine → MVCC transactions: uses MVCC (evidence: `src/sql/engine/engine.rs`)
- Execution plans → SQL executor: executes plan
- SQL executor → Aggregations and joins: delegates operators (evidence: `src/sql/execution/mod.rs`)
- SQL executor → SQL engine: reads and writes
- SQL and Raft server → Database cluster: serves SQL and Raft (evidence: `src/server.rs`)
- SQL and Raft server → Raft node: routes Raft requests (evidence: `src/server.rs`)
- Raft node → Raft log: manages log (evidence: `src/raft/node.rs`)
- Raft node → Raft messages: exchanges messages (evidence: `src/raft/node.rs`)
- Raft node → Raft state: applies state (evidence: `src/raft/node.rs`)
- Raft log → Storage engines: persists log (evidence: `src/raft/log.rs`)
- MVCC transactions → Storage engines: stores versions (evidence: `src/storage/mvcc.rs`)
- Storage engines → BitCask and memory: implemented by (evidence: `src/storage/mvcc.rs`)
- MVCC transactions → Key and value encoding: encodes keys (evidence: `src/storage/mvcc.rs`)
- Workload benchmark → Database cluster: benchmarks
- Database cluster → CSV experiment data: produces measurements
- CSV experiment data → Experiment data analysis: loads CSV (evidence: `plot/config.py`)
- Experiment data analysis → Experiment charts: supports charts (evidence: `plot/exp1/compare-latency.py`)
- Experiment analyst → Experiment charts: generates charts