# asdpresence/bustub_cmu15445 architecture

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

- Interactive diagram: https://gitdiagram.com/asdpresence/bustub_cmu15445
- Repository: https://github.com/asdpresence/bustub_cmu15445

## Overview

##### Main Architectural Components
- SQL Frontend & Query Processing:
- Components include the binder (located in src/binder) where the SQL queries are parsed and translated into internal representations.
- The planner and optimizer (in src/planner and src/optimizer) take the bound query and generate and refine the execution plan.
- Execution Engine:
- Present in src/execution. This module contains various executors (e.g., sequential scan, index scan, join, aggregation) which execute the query plan.
- Storage & Buffer Management:
- The storage subsystem is divided into components such as storage (src/storage), which manages table heaps, index files, and pages.
- Buffer management (src/buffer) handles the caching and replacement policies (with files like buffer_pool_manager_instance.cpp and replacer implementations).
- Catalog:
- The catalog (src/catalog) maintains metadata about tables, columns, and schemas.
- Concurrency & Transaction Management:
- In src/concurrency, you have the lock manager and transaction manager which are needed for providing isolation and consistency.
- Recovery:
- Recovery components (src/recovery) handle logging, checkpointing, and crash recovery.
- Container and Data Types:
- The project leverages container utilities (src/container) for disk and in-memory hash tables, and the type subsystem (src/type) for managing column data types.
- Supporting Libraries and Testing:
- There are third_party dependencies (e.g., fmt, libpg_query, googletest) integrated via CMake to support logging, parsing, and testing.
- The tests folder shows a well-established suite that verifies each module’s functionality.
- Tools & Shell:
- Tools like the interactive shell (tools/shell) and benchmark utilities (tools/terrier_bench etc.) provide external interfaces for interacting with the engine.

##### Relationships and Data Flow
- How an SQL command enters through an interactive shell or API, passes to the binder for parsing, moves on to the planner and optimizer for query plan generation, and then is handed off to the execution engine.
- Demonstrate how metadata from the catalog is used by the binder and planner.
- Recovery components interacting with the buffer/storage layers for logging and checkpointing in case of crashes.

##### Architectural Patterns & Design Principles
- The layered design separates concerns: SQL parsing and binding; query planning and optimization; execution; storage; and transaction management.

##### Relevant Technologies & Dependencies
- Use of CMake for build management and third_party libraries such as fmt (for formatting/logging) and libpg_query (for parsing functionalities).
- Mention the build support scripts (Dockerfile, Vagrantfile, etc.) which underline that the system is designed to be deployed/tested in multiple environments.
- The integration of testing frameworks (googletest) can be marked as part of the system’s verification/support infrastructure.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface"
        SHELL["SQL Shell (Interactive Shell)"]:::frontend
    end

    %% Query Processing Layer
    subgraph "Query Processing Layer"
        BINDER["Binder (SQL Parsing & Binding)"]:::frontend
        PLANNER["Planner"]:::frontend
        OPTIMIZER["Optimizer"]:::frontend
    end

    %% Execution Engine Layer
    subgraph "Execution Engine Layer"
        EXECUTION["Execution Engine"]:::execution
    end

    %% Data Management Layer
    subgraph "Data Management Layer"
        BUFFER["Buffer Management"]:::data
        STORAGE["Storage Manager"]:::storage
        CATALOG["Catalog Manager"]:::catalog
    end

    %% Transaction & Recovery Layer
    subgraph "Transaction & Recovery Layer"
        CONCURRENCY["Concurrency & Transaction Manager"]:::control
        RECOVERY["Recovery Manager"]:::control
    end

    %% Support Utilities
    subgraph "Support Utilities"
        CONTAINER["Container Utilities"]:::support
        DATATYPE["Data Types"]:::support
    end

    %% Relationships
    SHELL -->|"submits_query"| BINDER
    BINDER -->|"binds_query"| PLANNER
    PLANNER -->|"plans_query"| OPTIMIZER
    OPTIMIZER -->|"optimizes_query"| EXECUTION
    EXECUTION -->|"executes_plan"| BUFFER
    BUFFER -->|"fetches_stores_pages"| STORAGE

    BINDER -->|"accesses_metadata"| CATALOG
    PLANNER -->|"uses_metadata"| CATALOG

    EXECUTION -->|"manages_transactions"| CONCURRENCY
    EXECUTION -->|"triggers_recovery"| RECOVERY
    BUFFER -->|"assists_recovery"| RECOVERY

    STORAGE -->|"utilizes_containers"| CONTAINER
    STORAGE -->|"interprets_types"| DATATYPE

    %% Click Events
    click SHELL "https://github.com/asdpresence/bustub_cmu15445/tree/main/tools/shell"
    click BINDER "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/binder"
    click PLANNER "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/planner"
    click OPTIMIZER "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/optimizer"
    click EXECUTION "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/execution"
    click BUFFER "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/buffer"
    click STORAGE "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/storage"
    click CATALOG "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/catalog"
    click CONCURRENCY "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/concurrency"
    click RECOVERY "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/recovery"
    click CONTAINER "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/container"
    click DATATYPE "https://github.com/asdpresence/bustub_cmu15445/tree/main/src/type"

    %% Styles
    classDef frontend fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef execution fill:#ccffcc,stroke:#008800,stroke-width:2px;
    classDef data fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef storage fill:#ccffff,stroke:#00cccc,stroke-width:2px;
    classDef catalog fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef control fill:#e6ccff,stroke:#9933ff,stroke-width:2px;
    classDef support fill:#f2f2f2,stroke:#666666,stroke-width:2px;
```
