# nandinideshmukh/minisql architecture

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

- Interactive diagram: https://gitdiagram.com/nandinideshmukh/minisql
- Repository: https://github.com/nandinideshmukh/minisql

## Overview

miniSQL is a local C SQL database. The current workflow is CLI input → parsing → executor dispatch, with V2 operations using a B+ tree index, heap pages, a buffer pool and WAL; V2 data and logs persist in files. The README also documents a V1 flat-file engine and V2 recovery-related code exists. V1’s runtime wiring and recovery invocation are not established by the sampled excerpts, so those links are omitted or marked unverified.

Main entry points: [`cfiles/src/executor/executor.c`](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/executor/executor.c) (Command Executor), [`cfiles/src/cli/cli.c`](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/cli/cli.c) (CLI / REPL), [`cfiles/src/buffer/buffer.c`](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/buffer/buffer.c) (Buffer Pool), [`cfiles/src/btree/btree.c`](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/btree/btree.c) (B+ Tree Index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["SQL Interface"]
  node_main["Program Entry<br/>[main.c]"]
  node_cli["CLI / REPL<br/>[cli.c]"]
  node_parser["SQL Parser<br/>[parser.c]"]
end

subgraph group_execution["Query Execution"]
  node_executor["Command Executor<br/>[executor.c]"]
end

subgraph group_engine["V2 Storage Engine"]
  node_btree["B+ Tree Index<br/>[btree.c]"]
  node_heap["Heap Pages<br/>[page.c]"]
  node_buffer["Buffer Pool<br/>[buffer.c]"]
  node_wal["Write-Ahead Log<br/>[wal.c]"]
  node_recovery["WAL Recovery<br/>[recovery.c]"]
  node_v2file[("V2 Database File")]
  node_logfile[("WAL Log File")]
end

subgraph group_legacy["V1 Flat-File Engine"]
  node_flatstorage["Flat-File Storage<br/>[storage.c]"]
  node_v1file[("V1 Database File")]
end

node_user(("SQL User"))

node_user -->|"enters SQL"| node_cli
node_main -->|"runs"| node_cli
node_cli -->|"parses input"| node_parser
node_cli -->|"dispatches commands"| node_executor
node_executor -->|"index operations"| node_btree
node_executor -->|"row operations"| node_heap
node_executor -->|"fetches pages"| node_buffer
node_executor -->|"writes transactions"| node_wal
node_btree -->|"stores row IDs"| node_heap
node_btree -->|"uses page cache"| node_buffer
node_heap -->|"uses page cache"| node_buffer
node_buffer -->|"reads and flushes"| node_v2file
node_wal -->|"records log"| node_logfile
node_wal -.-> node_recovery
node_flatstorage -->|"reads and writes"| node_v1file

click node_main "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/main.c"
click node_cli "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/cli/cli.c"
click node_parser "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/parser/parser.c"
click node_executor "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/executor/executor.c"
click node_btree "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/btree/btree.c"
click node_heap "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/page/page.c"
click node_buffer "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/buffer/buffer.c"
click node_wal "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/wal/wal.c"
click node_recovery "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/wal/recovery.c"
click node_flatstorage "https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/storage/storage.c"

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_main,node_cli,node_parser,node_user toneBlue
class node_executor toneAmber
class node_btree,node_heap,node_buffer,node_wal,node_recovery,node_v2file,node_logfile toneMint
class node_flatstorage,node_v1file toneRose
```

## Components

### SQL Interface

- [Program Entry](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/main.c): `cfiles/src/main.c`
- [CLI / REPL](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/cli/cli.c): `cfiles/src/cli/cli.c`
- [SQL Parser](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/parser/parser.c): `cfiles/src/parser/parser.c`

### Query Execution

- [Command Executor](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/executor/executor.c): `cfiles/src/executor/executor.c`

### V2 Storage Engine

- [B+ Tree Index](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/btree/btree.c): `cfiles/src/btree/btree.c`
- [Heap Pages](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/page/page.c): `cfiles/src/page/page.c`
- [Buffer Pool](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/buffer/buffer.c): `cfiles/src/buffer/buffer.c`
- [Write-Ahead Log](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/wal/wal.c): `cfiles/src/wal/wal.c`
- [WAL Recovery](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/wal/recovery.c): `cfiles/src/wal/recovery.c`
- **V2 Database File**
- **WAL Log File**

### V1 Flat-File Engine

- [Flat-File Storage](https://github.com/nandinideshmukh/minisql/blob/main/cfiles/src/storage/storage.c): `cfiles/src/storage/storage.c`
- **V1 Database File**

### Other components

- **SQL User**

## Connections

- SQL User → CLI / REPL: enters SQL (evidence: `README.md`)
- Program Entry → CLI / REPL: runs (evidence: `cfiles/src/main.c`)
- CLI / REPL → SQL Parser: parses input (evidence: `README.md`)
- CLI / REPL → Command Executor: dispatches commands (evidence: `README.md`)
- Command Executor → B+ Tree Index: index operations (evidence: `cfiles/src/executor/executor.c`)
- Command Executor → Heap Pages: row operations (evidence: `cfiles/src/executor/executor.c`)
- Command Executor → Buffer Pool: fetches pages (evidence: `cfiles/src/executor/executor.c`)
- Command Executor → Write-Ahead Log: writes transactions (evidence: `cfiles/src/executor/executor.c`)
- B+ Tree Index → Heap Pages: stores row IDs (evidence: `README.md`)
- B+ Tree Index → Buffer Pool: uses page cache (evidence: `README.md`)
- Heap Pages → Buffer Pool: uses page cache (evidence: `README.md`)
- Buffer Pool → V2 Database File: reads and flushes (evidence: `README.md`)
- Write-Ahead Log → WAL Log File: records log (evidence: `README.md`)
- Write-Ahead Log → WAL Recovery
- Flat-File Storage → V1 Database File: reads and writes (evidence: `README.md`)