# mainak9093/asterdb architecture

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

- Interactive diagram: https://gitdiagram.com/mainak9093/asterdb
- Repository: https://github.com/mainak9093/asterdb

## Overview

AsterDB is a single-threaded, in-memory analytical SQL engine. Its principal workflow accepts SQL, parses and binds it, optimizes a logical plan, plans and executes a batch-oriented operator tree, then returns results. A separate LOAD path reads CSV tables into the session catalog. The README also documents selection-vector filtering, dictionary-encoded strings, configurable optimizer rewrites, EXPLAIN, and selectable hash or nested-loop joins. Some operator and storage implementations were not excerpted; edges to them are limited to planner references or documented behavior.

Main entry points: [`src/main.cpp`](https://github.com/mainak9093/asterdb/blob/main/src/main.cpp) (Session dispatch), [`src/execution/planner.cpp`](https://github.com/mainak9093/asterdb/blob/main/src/execution/planner.cpp) (Physical planner), [`src/storage/catalog.cpp`](https://github.com/mainak9093/asterdb/blob/main/src/storage/catalog.cpp) (Table catalog), [`src/storage/column.cpp`](https://github.com/mainak9093/asterdb/blob/main/src/storage/column.cpp) (Column storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Session interface"]
  node_session["Session dispatch<br/>[main.cpp]"]
end

subgraph group_sql["SQL planning"]
  node_lexer["Lexer<br/>[lexer.cpp]"]
  node_parser["SQL parser<br/>[parser.cpp]"]
  node_binder["Name binder<br/>[binder.cpp]"]
  node_logical["Logical plan<br/>[logical_plan.cpp]"]
  node_optimizer["Rewrite rules<br/>[rules.cpp]"]
end

subgraph group_execution["Query execution"]
  node_planner["Physical planner<br/>[planner.cpp]"]
  node_executor["Operator executor<br/>[executor.cpp]"]
  node_scan["Sequential scan<br/>[seq_scan.cpp]"]
  node_filter["Filter operator<br/>[filter_op.cpp]"]
  node_join["Join operators<br/>[join_op.cpp]"]
  node_aggregate["Hash aggregate<br/>[hash_aggregate.cpp]"]
  node_project["Projection<br/>[project_op.cpp]"]
  node_sort["Sort<br/>[sort_op.cpp]"]
  node_limit["Limit<br/>[limit_op.cpp]"]
  node_materialize["Materialization<br/>[materialize.cpp]"]
end

subgraph group_storage["Columnar storage"]
  node_csv["CSV reader<br/>[csv_reader.cpp]"]
  node_catalog[("Table catalog<br/>[catalog.cpp]")]
  node_table[("Columnar tables<br/>[table.cpp]")]
  node_column["Column storage<br/>[column.cpp]"]
  node_filterkernel["Filter kernel<br/>[filter_kernel.cpp]"]
  node_dictionary["String dictionary<br/>[dictionary.cpp]"]
end

subgraph group_shared["Shared runtime"]
  node_types["Types and status<br/>[types.h]"]
end

node_user(("SQL user"))

node_user -->|"submits SQL"| node_session
node_session -->|"parses SQL"| node_parser
node_parser -->|"tokenizes input"| node_lexer
node_session -->|"binds statement"| node_binder
node_binder -->|"builds plan"| node_logical
node_session -->|"optimizes plan"| node_optimizer
node_optimizer -->|"rewrites plan"| node_logical
node_session -->|"plans query"| node_planner
node_planner -->|"creates operators"| node_scan
node_planner -->|"creates operators"| node_filter
node_planner -->|"creates operators"| node_join
node_planner -->|"creates operators"| node_aggregate
node_planner -->|"creates operators"| node_project
node_planner -->|"creates operators"| node_sort
node_planner -->|"creates operators"| node_limit
node_session -->|"executes tree"| node_executor
node_executor -->|"returns result status"| node_types
node_session -->|"loads CSV"| node_csv
node_session -->|"registers table"| node_catalog
node_csv -->|"builds table"| node_table
node_catalog -->|"stores tables"| node_table
node_scan -->|"reads table"| node_catalog
node_filter -.->|"filters columns"| node_filterkernel
node_filterkernel -->|"reads column data"| node_column
node_column -->|"encodes strings"| node_dictionary
node_join -->|"drains child rows"| node_materialize
node_materialize -->|"builds output columns"| node_column
node_aggregate -->|"uses SQL types"| node_types

click node_session "https://github.com/mainak9093/asterdb/blob/main/src/main.cpp"
click node_lexer "https://github.com/mainak9093/asterdb/blob/main/src/parser/lexer.cpp"
click node_parser "https://github.com/mainak9093/asterdb/blob/main/src/parser/parser.cpp"
click node_binder "https://github.com/mainak9093/asterdb/blob/main/src/optimizer/binder.cpp"
click node_logical "https://github.com/mainak9093/asterdb/blob/main/src/optimizer/logical_plan.cpp"
click node_optimizer "https://github.com/mainak9093/asterdb/blob/main/src/optimizer/rules.cpp"
click node_planner "https://github.com/mainak9093/asterdb/blob/main/src/execution/planner.cpp"
click node_executor "https://github.com/mainak9093/asterdb/blob/main/src/execution/executor.cpp"
click node_scan "https://github.com/mainak9093/asterdb/blob/main/src/execution/seq_scan.cpp"
click node_filter "https://github.com/mainak9093/asterdb/blob/main/src/execution/filter_op.cpp"
click node_join "https://github.com/mainak9093/asterdb/blob/main/src/execution/join_op.cpp"
click node_aggregate "https://github.com/mainak9093/asterdb/blob/main/src/execution/hash_aggregate.cpp"
click node_project "https://github.com/mainak9093/asterdb/blob/main/src/execution/project_op.cpp"
click node_sort "https://github.com/mainak9093/asterdb/blob/main/src/execution/sort_op.cpp"
click node_limit "https://github.com/mainak9093/asterdb/blob/main/src/execution/limit_op.cpp"
click node_materialize "https://github.com/mainak9093/asterdb/blob/main/src/execution/materialize.cpp"
click node_csv "https://github.com/mainak9093/asterdb/blob/main/src/storage/csv_reader.cpp"
click node_catalog "https://github.com/mainak9093/asterdb/blob/main/src/storage/catalog.cpp"
click node_table "https://github.com/mainak9093/asterdb/blob/main/src/storage/table.cpp"
click node_column "https://github.com/mainak9093/asterdb/blob/main/src/storage/column.cpp"
click node_filterkernel "https://github.com/mainak9093/asterdb/blob/main/src/storage/filter_kernel.cpp"
click node_dictionary "https://github.com/mainak9093/asterdb/blob/main/src/storage/dictionary.cpp"
click node_types "https://github.com/mainak9093/asterdb/blob/main/include/common/types.h"

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_session,node_user toneBlue
class node_lexer,node_parser,node_binder,node_logical,node_optimizer toneAmber
class node_planner,node_executor,node_scan,node_filter,node_join,node_aggregate,node_project,node_sort,node_limit,node_materialize toneMint
class node_csv,node_catalog,node_table,node_column,node_filterkernel,node_dictionary toneRose
class node_types toneIndigo
```

## Components

### Session interface

- [Session dispatch](https://github.com/mainak9093/asterdb/blob/main/src/main.cpp): `src/main.cpp`

### SQL planning

- [Lexer](https://github.com/mainak9093/asterdb/blob/main/src/parser/lexer.cpp): `src/parser/lexer.cpp`
- [SQL parser](https://github.com/mainak9093/asterdb/blob/main/src/parser/parser.cpp): `src/parser/parser.cpp`
- [Name binder](https://github.com/mainak9093/asterdb/blob/main/src/optimizer/binder.cpp): `src/optimizer/binder.cpp`
- [Logical plan](https://github.com/mainak9093/asterdb/blob/main/src/optimizer/logical_plan.cpp): `src/optimizer/logical_plan.cpp`
- [Rewrite rules](https://github.com/mainak9093/asterdb/blob/main/src/optimizer/rules.cpp): `src/optimizer/rules.cpp`

### Query execution

- [Physical planner](https://github.com/mainak9093/asterdb/blob/main/src/execution/planner.cpp): `src/execution/planner.cpp`
- [Operator executor](https://github.com/mainak9093/asterdb/blob/main/src/execution/executor.cpp): `src/execution/executor.cpp`
- [Sequential scan](https://github.com/mainak9093/asterdb/blob/main/src/execution/seq_scan.cpp): `src/execution/seq_scan.cpp`
- [Filter operator](https://github.com/mainak9093/asterdb/blob/main/src/execution/filter_op.cpp): `src/execution/filter_op.cpp`
- [Join operators](https://github.com/mainak9093/asterdb/blob/main/src/execution/join_op.cpp): `src/execution/join_op.cpp`
- [Hash aggregate](https://github.com/mainak9093/asterdb/blob/main/src/execution/hash_aggregate.cpp): `src/execution/hash_aggregate.cpp`
- [Projection](https://github.com/mainak9093/asterdb/blob/main/src/execution/project_op.cpp): `src/execution/project_op.cpp`
- [Sort](https://github.com/mainak9093/asterdb/blob/main/src/execution/sort_op.cpp): `src/execution/sort_op.cpp`
- [Limit](https://github.com/mainak9093/asterdb/blob/main/src/execution/limit_op.cpp): `src/execution/limit_op.cpp`
- [Materialization](https://github.com/mainak9093/asterdb/blob/main/src/execution/materialize.cpp): `src/execution/materialize.cpp`

### Columnar storage

- [CSV reader](https://github.com/mainak9093/asterdb/blob/main/src/storage/csv_reader.cpp): `src/storage/csv_reader.cpp`
- [Table catalog](https://github.com/mainak9093/asterdb/blob/main/src/storage/catalog.cpp): `src/storage/catalog.cpp`
- [Columnar tables](https://github.com/mainak9093/asterdb/blob/main/src/storage/table.cpp): `src/storage/table.cpp`
- [Column storage](https://github.com/mainak9093/asterdb/blob/main/src/storage/column.cpp): `src/storage/column.cpp`
- [Filter kernel](https://github.com/mainak9093/asterdb/blob/main/src/storage/filter_kernel.cpp): `src/storage/filter_kernel.cpp`
- [String dictionary](https://github.com/mainak9093/asterdb/blob/main/src/storage/dictionary.cpp): `src/storage/dictionary.cpp`

### Shared runtime

- [Types and status](https://github.com/mainak9093/asterdb/blob/main/include/common/types.h): `include/common/types.h`

### Other components

- **SQL user**

## Connections

- SQL user → Session dispatch: submits SQL (evidence: `README.md`)
- Session dispatch → SQL parser: parses SQL (evidence: `src/main.cpp`)
- SQL parser → Lexer: tokenizes input (evidence: `src/parser/parser.cpp`)
- Session dispatch → Name binder: binds statement (evidence: `src/main.cpp`)
- Name binder → Logical plan: builds plan (evidence: `src/optimizer/binder.cpp`)
- Session dispatch → Rewrite rules: optimizes plan (evidence: `src/main.cpp`)
- Rewrite rules → Logical plan: rewrites plan (evidence: `src/optimizer/rules.cpp`)
- Session dispatch → Physical planner: plans query (evidence: `src/main.cpp`)
- Physical planner → Sequential scan: creates operators (evidence: `src/execution/planner.cpp`)
- Physical planner → Filter operator: creates operators (evidence: `src/execution/planner.cpp`)
- Physical planner → Join operators: creates operators (evidence: `src/execution/planner.cpp`)
- Physical planner → Hash aggregate: creates operators (evidence: `src/execution/planner.cpp`)
- Physical planner → Projection: creates operators (evidence: `src/execution/planner.cpp`)
- Physical planner → Sort: creates operators (evidence: `src/execution/planner.cpp`)
- Physical planner → Limit: creates operators (evidence: `src/execution/planner.cpp`)
- Session dispatch → Operator executor: executes tree (evidence: `src/main.cpp`)
- Operator executor → Types and status: returns result status
- Session dispatch → CSV reader: loads CSV (evidence: `src/main.cpp`)
- Session dispatch → Table catalog: registers table (evidence: `src/main.cpp`)
- CSV reader → Columnar tables: builds table
- Table catalog → Columnar tables: stores tables
- Sequential scan → Table catalog: reads table
- Filter operator → Filter kernel: filters columns
- Filter kernel → Column storage: reads column data
- Column storage → String dictionary: encodes strings
- Join operators → Materialization: drains child rows
- Materialization → Column storage: builds output columns
- Hash aggregate → Types and status: uses SQL types
