# ryogrid/samehadadb architecture

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

- Interactive diagram: https://gitdiagram.com/ryogrid/samehadadb
- Repository: https://github.com/ryogrid/samehadadb

## Overview

SamehadaDB is a learning-oriented relational database, usable as an embedded library or through a REST server. The principal workflow accepts SQL, parses and plans it, executes relational operators over catalogued tables and indexes, and returns rows. The repository also documents transactions, logging, recovery, checkpointing, and optimizer statistics. Some relationships below rely on README statements or SOURCE INDEX references because their implementation excerpts were not provided; those limits are reflected in the evidence paths.

Main entry points: [`lib/samehada/samehada.go`](https://github.com/ryogrid/samehadadb/blob/master/lib/samehada/samehada.go) (Database API), [`lib/execution/executors`](https://github.com/ryogrid/samehadadb/tree/master/lib/execution/executors) (Query operators), [`lib/recovery/log_manager.go`](https://github.com/ryogrid/samehadadb/blob/master/lib/recovery/log_manager.go) (Log manager), [`lib/concurrency/checkpoint_manager.go`](https://github.com/ryogrid/samehadadb/blob/master/lib/concurrency/checkpoint_manager.go) (Checkpoint manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["SQL interfaces"]
  node_rest["REST endpoints<br/>[main.go]"]
  node_database["Database API<br/>[samehada.go]"]
end

subgraph group_query["Query processing"]
  node_parser["SQL parser<br/>[parser.go]"]
  node_expressions["SQL expressions"]
  node_planner["Simple planner<br/>[simple_planner.go]"]
  node_optimizer["Selinger optimizer"]
  node_plans["Query plans"]
  node_engine["Execution engine"]
  node_operators["Query operators"]
end

subgraph group_data["Catalog and storage"]
  node_catalog[("Table catalog<br/>[table_catalog.go]")]
  node_statistics["Optimizer statistics<br/>[statistics.go]"]
  node_heap[("Table heap<br/>[table_heap.go]")]
  node_indexes[("Indexes")]
  node_buffer["Buffer pool"]
  node_disk[("Disk manager")]
end

subgraph group_reliability["Transactions and recovery"]
  node_transactions["Transaction manager"]
  node_locks["Lock manager<br/>[lock_manager.go]"]
  node_logging["Log manager<br/>[log_manager.go]"]
  node_recovery["Log recovery<br/>[log_recovery.go]"]
  node_checkpoint["Checkpoint manager"]
end

node_client(("SQL client"))

node_client -->|"submits SQL"| node_database
node_client -->|"sends JSON"| node_rest
node_rest -->|"executes SQL"| node_database
node_database -->|"parses SQL"| node_parser
node_parser -->|"builds expressions"| node_expressions
node_database -->|"plans queries"| node_planner
node_planner -->|"optimizes plans"| node_optimizer
node_planner -->|"creates plans"| node_plans
node_optimizer -->|"uses estimates"| node_statistics
node_database -->|"executes plans"| node_engine
node_engine -->|"dispatches plans"| node_plans
node_engine -->|"creates operators"| node_operators
node_operators -.->|"accesses metadata"| node_catalog
node_operators -.->|"scans and modifies"| node_heap
node_operators -.->|"uses indexes"| node_indexes
node_catalog -->|"manages tables"| node_heap
node_transactions -.->|"coordinates locks"| node_locks
node_transactions -->|"records transactions"| node_logging
node_buffer -->|"reads and writes pages"| node_disk
node_buffer -->|"logs page changes"| node_logging
node_recovery -->|"replays log"| node_logging
node_checkpoint -->|"blocks transactions"| node_transactions
node_checkpoint -->|"flushes pages"| node_buffer
node_checkpoint -->|"flushes log"| node_logging

click node_rest "https://github.com/ryogrid/samehadadb/blob/master/server/main.go"
click node_database "https://github.com/ryogrid/samehadadb/blob/master/lib/samehada/samehada.go"
click node_parser "https://github.com/ryogrid/samehadadb/blob/master/lib/parser/parser.go"
click node_expressions "https://github.com/ryogrid/samehadadb/blob/master/lib/parser/parser_expressions.go"
click node_planner "https://github.com/ryogrid/samehadadb/blob/master/lib/planner/simple_planner.go"
click node_optimizer "https://github.com/ryogrid/samehadadb/blob/master/lib/planner/optimizer/selinger_optimizer.go"
click node_plans "https://github.com/ryogrid/samehadadb/tree/master/lib/execution/plans"
click node_engine "https://github.com/ryogrid/samehadadb/blob/master/lib/execution/executors/execution_engine.go"
click node_operators "https://github.com/ryogrid/samehadadb/tree/master/lib/execution/executors"
click node_catalog "https://github.com/ryogrid/samehadadb/blob/master/lib/catalog/table_catalog.go"
click node_statistics "https://github.com/ryogrid/samehadadb/blob/master/lib/catalog/statistics.go"
click node_heap "https://github.com/ryogrid/samehadadb/blob/master/lib/storage/access/table_heap.go"
click node_indexes "https://github.com/ryogrid/samehadadb/tree/master/lib/storage/index"
click node_transactions "https://github.com/ryogrid/samehadadb/blob/master/lib/storage/access/transaction_manager.go"
click node_locks "https://github.com/ryogrid/samehadadb/blob/master/lib/storage/access/lock_manager.go"
click node_buffer "https://github.com/ryogrid/samehadadb/blob/master/lib/storage/buffer/buffer_pool_manager.go"
click node_disk "https://github.com/ryogrid/samehadadb/blob/master/lib/storage/disk/disk_manager_impl.go"
click node_logging "https://github.com/ryogrid/samehadadb/blob/master/lib/recovery/log_manager.go"
click node_recovery "https://github.com/ryogrid/samehadadb/blob/master/lib/recovery/log_recovery/log_recovery.go"
click node_checkpoint "https://github.com/ryogrid/samehadadb/blob/master/lib/concurrency/checkpoint_manager.go"

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_rest,node_database,node_client toneBlue
class node_parser,node_expressions,node_planner,node_optimizer,node_plans,node_engine,node_operators toneAmber
class node_catalog,node_statistics,node_heap,node_indexes,node_buffer,node_disk toneMint
class node_transactions,node_locks,node_logging,node_recovery,node_checkpoint toneRose
```

## Components

### SQL interfaces

- [REST endpoints](https://github.com/ryogrid/samehadadb/blob/master/server/main.go): `server/main.go`
- [Database API](https://github.com/ryogrid/samehadadb/blob/master/lib/samehada/samehada.go): `lib/samehada/samehada.go`

### Query processing

- [SQL parser](https://github.com/ryogrid/samehadadb/blob/master/lib/parser/parser.go): `lib/parser/parser.go`
- [SQL expressions](https://github.com/ryogrid/samehadadb/blob/master/lib/parser/parser_expressions.go): `lib/parser/parser_expressions.go`
- [Simple planner](https://github.com/ryogrid/samehadadb/blob/master/lib/planner/simple_planner.go): `lib/planner/simple_planner.go`
- [Selinger optimizer](https://github.com/ryogrid/samehadadb/blob/master/lib/planner/optimizer/selinger_optimizer.go): `lib/planner/optimizer/selinger_optimizer.go`
- [Query plans](https://github.com/ryogrid/samehadadb/tree/master/lib/execution/plans): `lib/execution/plans`
- [Execution engine](https://github.com/ryogrid/samehadadb/blob/master/lib/execution/executors/execution_engine.go): `lib/execution/executors/execution_engine.go`
- [Query operators](https://github.com/ryogrid/samehadadb/tree/master/lib/execution/executors): `lib/execution/executors`

### Catalog and storage

- [Table catalog](https://github.com/ryogrid/samehadadb/blob/master/lib/catalog/table_catalog.go): `lib/catalog/table_catalog.go`
- [Optimizer statistics](https://github.com/ryogrid/samehadadb/blob/master/lib/catalog/statistics.go): `lib/catalog/statistics.go`
- [Table heap](https://github.com/ryogrid/samehadadb/blob/master/lib/storage/access/table_heap.go): `lib/storage/access/table_heap.go`
- [Indexes](https://github.com/ryogrid/samehadadb/tree/master/lib/storage/index): `lib/storage/index`
- [Buffer pool](https://github.com/ryogrid/samehadadb/blob/master/lib/storage/buffer/buffer_pool_manager.go): `lib/storage/buffer/buffer_pool_manager.go`
- [Disk manager](https://github.com/ryogrid/samehadadb/blob/master/lib/storage/disk/disk_manager_impl.go): `lib/storage/disk/disk_manager_impl.go`

### Transactions and recovery

- [Transaction manager](https://github.com/ryogrid/samehadadb/blob/master/lib/storage/access/transaction_manager.go): `lib/storage/access/transaction_manager.go`
- [Lock manager](https://github.com/ryogrid/samehadadb/blob/master/lib/storage/access/lock_manager.go): `lib/storage/access/lock_manager.go`
- [Log manager](https://github.com/ryogrid/samehadadb/blob/master/lib/recovery/log_manager.go): `lib/recovery/log_manager.go`
- [Log recovery](https://github.com/ryogrid/samehadadb/blob/master/lib/recovery/log_recovery/log_recovery.go): `lib/recovery/log_recovery/log_recovery.go`
- [Checkpoint manager](https://github.com/ryogrid/samehadadb/blob/master/lib/concurrency/checkpoint_manager.go): `lib/concurrency/checkpoint_manager.go`

### Other components

- **SQL client**

## Connections

- SQL client → Database API: submits SQL
- SQL client → REST endpoints: sends JSON
- REST endpoints → Database API: executes SQL (evidence: `server/main.go`)
- Database API → SQL parser: parses SQL (evidence: `lib/samehada/samehada.go`)
- SQL parser → SQL expressions: builds expressions (evidence: `lib/parser/parser_expressions.go`)
- Database API → Simple planner: plans queries (evidence: `lib/samehada/samehada.go`)
- Simple planner → Selinger optimizer: optimizes plans (evidence: `lib/planner/simple_planner.go`)
- Simple planner → Query plans: creates plans (evidence: `lib/planner/simple_planner.go`)
- Selinger optimizer → Optimizer statistics: uses estimates (evidence: `lib/planner/optimizer/selinger_optimizer.go`)
- Database API → Execution engine: executes plans (evidence: `lib/samehada/samehada.go`)
- Execution engine → Query plans: dispatches plans (evidence: `lib/execution/executors/execution_engine.go`)
- Execution engine → Query operators: creates operators (evidence: `lib/execution/executors/execution_engine.go`)
- Query operators → Table catalog: accesses metadata
- Query operators → Table heap: scans and modifies
- Query operators → Indexes: uses indexes
- Table catalog → Table heap: manages tables (evidence: `lib/catalog/table_catalog.go`)
- Transaction manager → Lock manager: coordinates locks
- Transaction manager → Log manager: records transactions (evidence: `lib/storage/access/transaction_manager.go`)
- Buffer pool → Disk manager: reads and writes pages (evidence: `lib/storage/buffer/buffer_pool_manager.go`)
- Buffer pool → Log manager: logs page changes (evidence: `lib/storage/buffer/buffer_pool_manager.go`)
- Log recovery → Log manager: replays log (evidence: `lib/recovery/log_recovery/log_recovery.go`)
- Checkpoint manager → Transaction manager: blocks transactions (evidence: `lib/concurrency/checkpoint_manager.go`)
- Checkpoint manager → Buffer pool: flushes pages (evidence: `lib/concurrency/checkpoint_manager.go`)
- Checkpoint manager → Log manager: flushes log (evidence: `lib/concurrency/checkpoint_manager.go`)
