# kj455/simple-db-go architecture

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

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

## Overview

##### Main Components
- Buffer Management: Represented by the packages under pkg/buffer. These modules handle in-memory buffering and management of database pages.
- File Management: Illustrated by the pkg/file package, which deals with physical file interactions (pages, blocks, etc.).
- Logging: The pkg/log package encapsulates the architecture for logging, including iterators and log managers.
- Parsing and Query Planning: Two layers here –
– Parsing: pkg/parse provides lexer, parser, and predicate parser functionalities to process SQL-like commands.
– Planning: pkg/plan lays out various plan components (select, project, update, etc.) necessary for the query execution.
- Query Execution: The pkg/query package handles the execution & scanning operators (e.g., table scans and project scans) that implement the query results.
- Record Management: The pkg/record package holds data layout definitions, schema management, and access on record levels.
- Transaction Management: pkg/tx is core to managing transactions including concurrency controls, locks, recovery, commit/rollback processes, and related logging integrations.
- Additional Helpers: Packages such as pkg/constant, pkg/time, and pkg/testutil support the overall system.

##### Relationships and Interactions
- A typical client (as seen in the playground/main.go) initiates database operations.
- The Query Parser (pkg/parse) consumes SQL-like commands which are transformed into an intermediate plan by the Query Planner (pkg/plan).
- The Query Engine (integrating pkg/query and pkg/record) uses the metadata (pkg/metadata) to understand table schema and execute data operations.
- The Transaction Manager (pkg/tx) surrounds the actions with transactional guarantees. It interacts with the Buffer Manager (pkg/buffer) for data caching and the Log Manager (pkg/log) for durability.
- File Storage (pkg/file) underpins persistent storage of data pages which are buffered and read/written by the system.
- Each component often calls helper interfaces or constants for standardized operations and configurations.

##### Architectural Patterns & Design Principles
- Modular design: The project is organized into distinct packages, making it easy to identify separate concerns (e.g., parsing vs. logging).
- Layered architecture: There’s a clear separation between the storage layer (file, buffer, record), the logic layer (planner, query, transaction), and the interface layer (parser/driver in playground/main.go).
- Encapsulation and interface use: Notice how many modules have associated “interface.go” files to define expected behaviors, which ensures loose coupling.
- Testing focus: There is an emphasis on testing (many *test.go files), suggesting a design that supports robust verification of each component.

##### Additional Practical Steps
- Drill down into each module to reveal sub-components if necessary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface and Query Processing Layer
    subgraph "Interface Layer"
        A["Client Interface"]:::interface
        B["Query Parsing (pkg/parse)"]:::query
        C["Query Planning (pkg/plan)"]:::query
        D["Query Execution (pkg/query & pkg/record)"]:::query
        E["Metadata Management (pkg/metadata)"]:::query
    end

    %% Data Storage and Transaction Management Layer
    subgraph "Data Storage Layer"
        F["Transaction Management (pkg/tx)"]:::storage
        G["Buffer Management (pkg/buffer)"]:::storage
        H["File Storage (pkg/file)"]:::storage
        I["Logging (pkg/log)"]:::storage
    end

    %% Connections between Interface and Query processing nodes
    A -->|"SQLCommand"| B
    B -->|"ParseResult"| C
    C -->|"ExecutionPlan"| D
    D -->|"SchemaLookup"| E
    E -->|"SchemaInfo"| D

    %% Connection from Query Execution to Transaction Management (for data update operations)
    D -->|"UpdateRecord"| F

    %% Connections within Data Storage Layer
    F -->|"BufferUpdate"| G
    G -->|"PersistPages"| H
    G -->|"LogBuffer"| I
    F -->|"Commit/Rollback"| I

    %% Click Events
    click A "https://github.com/kj455/simple-db-go/blob/main/playground/main.go"
    click B "https://github.com/kj455/simple-db-go/blob/main/pkg/parse/parser.go"
    click C "https://github.com/kj455/simple-db-go/blob/main/pkg/plan/basic_query_planner.go"
    click D "https://github.com/kj455/simple-db-go/blob/main/pkg/query/select_scan.go"
    click E "https://github.com/kj455/simple-db-go/blob/main/pkg/metadata/metadata_mgr.go"
    click F "https://github.com/kj455/simple-db-go/blob/main/pkg/tx/transaction.go"
    click G "https://github.com/kj455/simple-db-go/blob/main/pkg/buffer/buffer.go"
    click H "https://github.com/kj455/simple-db-go/blob/main/pkg/file/file_mgr.go"
    click I "https://github.com/kj455/simple-db-go/blob/main/pkg/log/log_mgr.go"

    %% Styles
    classDef interface fill:#bbf,stroke:#333,stroke-width:2px;
    classDef query fill:#cfc,stroke:#333,stroke-width:2px;
    classDef storage fill:#fcc,stroke:#333,stroke-width:2px;
```
