# definitelynotsalesman/hydradb architecture

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

- Interactive diagram: https://gitdiagram.com/definitelynotsalesman/hydradb
- Repository: https://github.com/definitelynotsalesman/hydradb

## Overview

##### Project type and purpose
- HydraDB is a standalone, monolithic C++ relational database engine.
- Its primary responsibilities are fast reads/writes on large datasets (via B+ trees), durability (via Write Ahead Logging), and an eventual goal of supporting concurrent transactions and in-memory caching.

##### File structure
- Top-level:
- database/ – the storage‐engine sources
– BTree.cpp/.hpp      → core B+ tree index implementation
– InputBuffer.cpp/.hpp → command/SQL input reader
– helper/Helper.cpp/.hpp → utility routines (e.g., serialization, logging helpers)
- src/ – entry points
– main.cpp            → orchestrates startup, command loop
– installer.cpp       → sets up initial on-disk structures (e.g., data files, WAL files)
- Absence of frontend/web/UI code implies a CLI tool or embeddable library.
- No external service or network layer is present—this is a pure storage engine.

##### README for additional insights
- Clearly defines the core features (B+ Tree, WAL, Pages) and future plans (Lock Manager, Cache).

- Break the system into: CLI, Query Processor, Storage Engine (and its submodules), Persistence Layer, Installer
- Concurrency or durability protocols (e.g., WAL write → fsync → page update)
- Keep it modular so it can expand when you add caching or locks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Execution Layer
    subgraph "Client/Execution Layer"
        direction TB
        InputBuffer["Client Interface: InputBuffer"]:::client
        QueryProcessor["Query Processor/Executor: main.cpp"]:::client
        Installer["Installer: installer.cpp"]:::client
    end

    %% Storage Engine Layer
    subgraph "Storage Engine Layer"
        direction TB
        PageManager["Page Manager"]:::storage
        BTreeManager["B+ Tree Index Manager"]:::storage
        WAL["Write-Ahead Log (WAL)"]:::storage
        LockManager["Lock Manager (Future)"]:::future
        CacheManager["Cache/Buffer Manager (Future)"]:::future
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DiskStorage["Raw File I/O on Disk"]:::persistence
    end

    %% Interactions
    InputBuffer -->|reads commands| QueryProcessor
    QueryProcessor -->|parses & dispatches| PageManager
    QueryProcessor -->|parses & dispatches| BTreeManager
    Installer -->|bootstraps files| DiskStorage

    BTreeManager -->|logs before write| WAL
    WAL -->|writes log & fsync| DiskStorage
    BTreeManager -->|reads/writes pages| PageManager
    PageManager -->|reads/writes pages| DiskStorage

    LockManager -.->|guards access| BTreeManager
    LockManager -.->|guards access| PageManager
    CacheManager -.->|caches pages| PageManager
    CacheManager -.->|serves index| BTreeManager

    %% Click Events
    click InputBuffer "https://github.com/definitelynotsalesman/hydradb/blob/main/database/InputBuffer.cpp"
    click BTreeManager "https://github.com/definitelynotsalesman/hydradb/blob/main/database/BTree.cpp"
    click WAL "https://github.com/definitelynotsalesman/hydradb/blob/main/database/helper/Helper.cpp"
    click QueryProcessor "https://github.com/definitelynotsalesman/hydradb/blob/main/src/main.cpp"
    click Installer "https://github.com/definitelynotsalesman/hydradb/blob/main/src/installer.cpp"

    %% Styles
    classDef client fill:#9f6,stroke:#393,stroke-width:2px
    classDef storage fill:#6cf,stroke:#039,stroke-width:2px
    classDef persistence fill:#bbb,stroke:#888,stroke-width:2px
    classDef future stroke-dasharray: 5 5,fill:none,stroke:#f66,stroke-width:2px
```
