# tomial/go-db architecture

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

- Interactive diagram: https://gitdiagram.com/tomial/go-db
- Repository: https://github.com/tomial/go-db

## Overview

##### Main Components
- Command Interface: The "cmd/godb.go" file indicates that the database is started as a standalone executable. The REPL (found under internal/repl) lets users interact with the database.
- Query Processor: Although not explicitly separated as “query evaluator,” the REPL and related buffer/stm components handle interpreting simple SQL commands.
- Storage Engine:
- B+Tree: The “internal/btree” folder contains the core logic for implementing the B+Tree. Include components like leaf, node, and overall tree management.
- Pager: Located in internal/pager, this component abstracts file/page I/O for reading and writing data pages to disk.
- Storage/Table Layer: The “internal/storage/table.go” file manages table-level logic (storing and retrieving rows).
- Data Representation: Modules like “internal/row” (which holds row, serialization, and cursor management) and “internal/datatype” handle the formatting and size/type details of stored records.
- Utilities and Constants: The “internal/constants” and “internal/util” directories provide support services like constant definitions and utility functions that all system components could use.

##### Relationships and Data Flow
- The entrypoint (cmd/godb.go) starts the REPL, which serves as the frontend for users entering SQL-like commands.
- The REPL interprets commands and triggers operations on the storage engine.
- For a write operation (e.g., insert):
- The command is processed by the REPL and passed to the table layer in “internal/storage.”
- The table layer interacts with the B+Tree (internal/btree) to manage indexing.
- The Pager (internal/pager) is used to persist the pages (representing tree nodes and table data) to disk.
- The row and serialization layers (internal/row) format the data for storage.
- For a read operation (e.g., select):
- The flow is similar, with the REPL sending a query to the storage layer,
- Which then uses the B+Tree for fast lookup, with the Pager handling data access.
- Utility functions and constant definitions support these interactions.

##### Architectural Patterns and Design Principles
- Modularity: Each functional area (REPL, Pager, Tree, Storage, Row operations) is isolated in its own subdirectory, promoting separation of concerns.
- Layered Architecture: You have a clear separation between user interaction (REPL) and backend processing (data storage and indexing).
- Testability: Several components have accompanying test files, which indicates that each module is designed to be unit-tested independently.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Command Interface Layer
    subgraph "Command Interface"
        Bootstrap("Application Bootstrap (cmd/godb.go)"):::interface
        REPL("REPL Command Processor (internal/repl)"):::interface
    end

    %% Storage Engine Layer
    subgraph "Storage Engine"
        TableStorage("Table Storage Module (internal/storage & internal/row)"):::engine
        BTree("B+Tree Indexing Module (internal/btree)"):::engine
        Pager("Data Pager (internal/pager)"):::engine
    end

    %% Support Modules Layer
    subgraph "Support Modules"
        DataFormat("Data Format Module (internal/datatype)"):::support
        Constants("Constants (internal/constants)"):::support
        Utilities("Utilities (internal/util)"):::support
    end

    %% Connections between layers
    Bootstrap -->|"start"| REPL
    REPL -->|"processes commands"| TableStorage
    TableStorage -->|"indexes"| BTree
    TableStorage -->|"persists data"| Pager
    TableStorage -->|"formats rows"| DataFormat
    BTree -.->|"loads pages"| Pager
    REPL -.->|"utilizes"| Constants
    REPL -.->|"utilizes"| Utilities
    TableStorage -.->|"defines"| Constants
    TableStorage -.->|"executes"| Utilities

    %% Click Events
    click Bootstrap "https://github.com/tomial/go-db/blob/master/cmd/godb.go"
    click REPL "https://github.com/tomial/go-db/tree/master/internal/repl"
    click BTree "https://github.com/tomial/go-db/tree/master/internal/btree"
    click Pager "https://github.com/tomial/go-db/tree/master/internal/pager"
    click TableStorage "https://github.com/tomial/go-db/blob/master/internal/storage/table.go"
    click DataFormat "https://github.com/tomial/go-db/tree/master/internal/datatype"
    click Constants "https://github.com/tomial/go-db/tree/master/internal/constants"
    click Utilities "https://github.com/tomial/go-db/tree/master/internal/util"

    %% Styles
    classDef interface fill:#ffdddd,stroke:#880000,stroke-width:2px;
    classDef engine fill:#ddffdd,stroke:#008800,stroke-width:2px;
    classDef support fill:#ddddff,stroke:#000088,stroke-width:2px;
```
