# simphp5/veldb architecture

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

- Interactive diagram: https://gitdiagram.com/simphp5/veldb
- Repository: https://github.com/simphp5/veldb

## Overview

##### Project type & purpose (from tree + README)
**VelDB** is an **intelligent database platform**: a database “core” (query engine + storage + transactions) exposed via **API services** (auth + query) and driven by a **web UI**, with an **AI/NL-to-SQL** capability layered on top.

The file tree strongly suggests a **layered architecture**:

- **ui/**: presentation layer (shared components + web app)
- **api/**: service layer (auth + query endpoints)
- **ai/**: AI feature module (natural language → SQL)
- **core/**: database kernel (query engine, storage engine, transaction manager)
- **devops/**: deployment/runtime infrastructure
- **docs/**: documentation

##### System Context (L1): who uses VelDB and what external systems it touches
- Auth/login + token usage
- Query execution (SQL) and NL query execution (NL → SQL → execution)

##### UI layer
From:
- `ui/web/` (web app)
- `ui/components/` (shared UI component library)

- **Web Client (VelDB UI)**
- Uses **Auth API** for login/session
- Uses **Query API** for query submission/results
- Optionally sends **natural language prompts** (either to Query API or AI service depending on how it’s wired)

##### API layer
From:
- `api/auth/` (authentication service)
- `api/query/` (query service)

- **Auth Service**
- Issues/validates tokens (JWT or similar)
- Stores/reads user identities (could be internal store or external IdP; confirm in `api/auth/README.md`)
- **Query Service**
- Accepts SQL queries (and possibly NL queries)
- Validates auth (calls Auth or validates tokens locally)
- Calls into **core query engine** for planning/execution
- Returns results/metadata to UI/clients

##### AI layer (NL-to-SQL)
From:
- `ai/nl_to_sql/`

- **Internal service** called by Query API (recommended depiction), or
- **Library module** used inside Query API (if it’s not deployed separately)

Likely external dependencies:
- **LLM provider** (OpenAI/Anthropic/local model) if mentioned in `ai/nl_to_sql/README.md`
- **Prompt templates / schema context** source (often pulled from catalog/metadata)

##### Database core (kernel)
From:
- `core/query_engine/`
- `core/storage/`
- `core/transaction/`

- **Query Engine**
- Parser / binder (logical)
- Optimizer / planner
- Execution engine (operators)
- Interfaces with Transaction + Storage
- **Transaction Manager**
- Concurrency control (locking/MVCC)
- WAL / commit log (if present)
- Coordinates atomicity/durability boundaries
- **Storage Engine**
- Page/record storage, file format
- Buffer/cache manager
- Indexes
- Catalog/metadata (if included here)

##### DevOps / Runtime
From:
- `devops/`

- Deployment units (containers/services)
- Networking boundaries (public vs private)
- Persistent volumes/disks for storage
- Observability (metrics/logging/tracing) if described

##### Documentation
From:
- `docs/`

##### Query API → UI: results + SQL used (important to show for transparency)

This flow is essential: it distinguishes VelDB from a typical DB.

##### Architectural patterns to highlight (based on structure)
- **Layered architecture**: UI → APIs → core kernel
- **Service separation** in `api/auth` vs `api/query` (even if co-deployed)
- **Kernel modularization**: query engine / storage / transactions are separated (classic DBMS architecture)
- **AI augmentation**: NL-to-SQL as a sidecar/library that transforms input into SQL, then uses the same execution path as normal queries

- Actors: end user, admin, external app/client (if applicable)
- System: “VelDB Platform”
- External systems: IdP, LLM provider, object storage, monitoring stack (only if real)

- Containers: `ui/web`, `api/auth`, `api/query`, `ai/nl_to_sql`, `core/*`, persistent storage
- Trust boundaries:
- Public zone: browser
- Edge: API services
- Private zone: core services + disks

- For `core/query_engine`: parser/planner/executor
- For `core/storage`: buffer manager, pages/files, indexes, catalog
- For `core/transaction`: lock manager/MVCC, WAL, recovery
- For `api/query`: routing, auth middleware, request validation, query submission, result formatting/streaming
- For `ai/nl_to_sql`: prompt builder, schema introspector, LLM client, SQL validator/sanitizer

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% L1 - System Context
  %% =========================
  subgraph "L1: System Context"
    direction TB

    User["End User"]:::actor
    Admin["Admin / Operator"]:::actor
    ExtClient["External App / Client"]:::actor

    VelDB["VelDB Platform"]:::system

    IdP["Identity Provider / User Store"]:::external
    LLM["LLM Provider"]:::external
    Mon["Monitoring / Logging Stack"]:::external

    User -->|"Uses"| VelDB
    ExtClient -->|"Uses"| VelDB
    Admin -->|"Operates"| VelDB

    VelDB -->|"Authn/Authz integration"| IdP
    VelDB -->|"NL-to-SQL inference calls"| LLM
    VelDB -->|"Metrics/logs/traces"| Mon
  end

  %% =========================
  %% L2 - Container Diagram
  %% =========================
  subgraph "L2: Containers (runtime/deployables)"
    direction TB

    %% --- Public Zone ---
    subgraph "Public Zone"
      direction TB
      WebUI["Web Client (VelDB UI)"]:::frontend
      UIComponents["Shared UI Component Library"]:::library
      WebUI -->|"Renders UI with"| UIComponents
    end

    %% --- Edge / API Zone ---
    subgraph "Edge Zone (APIs)"
      direction TB
      AuthSvc["Auth Service"]:::service
      QuerySvc["Query Service"]:::service
    end

    %% --- Private Zone ---
    subgraph "Private Zone (DB kernel + AI)"
      direction TB

      NLSQL["AI NL-to-SQL"]:::service

      subgraph "Database Core (Kernel)"
        direction TB
        CoreQE["Core Query Engine"]:::core
        CoreTX["Core Transaction Manager"]:::core
        CoreST["Core Storage Engine"]:::core
      end

      %% Persistence
      DataFiles[("Data Files / Pages / Indexes")]:::datastore
      WAL[("WAL / Commit Log")]:::datastore
      Catalog[("Catalog / Metadata Store")]:::datastore
    end

    %% UI -> APIs
    WebUI -->|"HTTPS/JSON: login/token"| AuthSvc
    WebUI -->|"HTTPS/JSON: SQL query + token"| QuerySvc
    WebUI -->|"HTTPS/JSON: NL query + token"| QuerySvc

    %% Query/Auth interaction
    QuerySvc -->|"Local call or HTTPS: ValidateToken"| AuthSvc
    AuthSvc -->|"Read/write identities"| IdP

    %% Query -> AI -> LLM
    QuerySvc -->|"Request: NL-to-SQL (schema context + prompt)"| NLSQL
    NLSQL -->|"HTTPS: inference call"| LLM
    NLSQL -->|"Response: SQL + confidence/explanation"| QuerySvc

    %% Query -> Core kernel
    QuerySvc -->|"RPC/Local: SubmitQuery(SQL)"| CoreQE

    %% Kernel triangle
    CoreQE -->|"Begin/commit/locks/snapshot"| CoreTX
    CoreQE -->|"Read/write records/pages/indexes"| CoreST
    CoreTX -->|"WAL/checkpoint coordination"| CoreST

    %% Storage -> persistence
    CoreST -->|"Persist pages/indexes"| DataFiles
    CoreTX -->|"Append/flush log"| WAL
    CoreST -->|"Schema/metadata"| Catalog

    %% Ops/observability
    QuerySvc -->|"Metrics/logs"| Mon
    AuthSvc -->|"Metrics/logs"| Mon
    NLSQL -->|"Metrics/logs"| Mon
  end

  %% =========================
  %% L3 - Component Diagrams
  %% =========================
  subgraph "L3: Components"
    direction TB

    %% --- api/query components ---
    subgraph "Query Service components"
      direction TB
      QRouter["HTTP Router / Controllers"]:::component
      QAuthMW["Auth Middleware (token enforcement)"]:::component
      QValidate["Request Validation / Sanitization"]:::component
      QDispatch["Query Dispatch (SQL vs NL)"]:::component
      QCoreClient["Core Client (submit/stream results)"]:::component
      QFormat["Result Formatting / Streaming"]:::component

      QRouter -->|"Calls"| QAuthMW
      QAuthMW -->|"Calls"| QValidate
      QValidate -->|"Calls"| QDispatch
      QDispatch -->|"Calls"| QCoreClient
      QCoreClient -->|"Calls"| QFormat
    end

    %% --- api/auth components ---
    subgraph "Auth Service components"
      direction TB
      ARouter["HTTP Router / Controllers"]:::component
      ACreds["Credential Verification"]:::component
      ATokens["Token Issuance / Validation"]:::component
      AUsers["User/Identity Store Adapter"]:::component

      ARouter -->|"Calls"| ACreds
      ACreds -->|"Reads"| AUsers
      ARouter -->|"Calls"| ATokens
      ATokens -->|"Reads/validates via"| AUsers
    end

    %% --- ai/nl_to_sql components ---
    subgraph "AI NL-to-SQL components"
      direction TB
      Prompt["Prompt Builder / Templates"]:::component
      SchemaCtx["Schema/Catalog Context Provider"]:::component
      LLMClient["LLM Client"]:::component
      SQLGuard["SQL Validator / Sanitizer"]:::component

      Prompt -->|"Uses"| SchemaCtx
      Prompt -->|"Builds prompt"| LLMClient
      LLMClient -->|"Returns draft SQL"| SQLGuard
    end

    %% --- core/query_engine components ---
    subgraph "Core Query Engine components"
      direction TB
      Parser["Parser / Binder"]:::component
      Planner["Optimizer / Planner"]:::component
      Executor["Execution Engine (operators)"]:::component

      Parser -->|"Produces logical plan"| Planner
      Planner -->|"Produces physical plan"| Executor
    end

    %% --- core/transaction components ---
    subgraph "Core Transaction Manager components"
      direction TB
      CC["Concurrency Control (Locking/MVCC)"]:::component
      TXN["Txn Coordinator (begin/commit/rollback)"]:::component
      Recovery["Recovery / Checkpoint"]:::component

      TXN -->|"Uses"| CC
      TXN -->|"Coordinates"| Recovery
    end

    %% --- core/storage components ---
    subgraph "Core Storage Engine components"
      direction TB
      Buffer["Buffer/Cache Manager"]:::component
      Pages["Page/Record Manager"]:::component
      Indexes["Indexes"]:::component
      CatalogMgr["Catalog/Metadata Manager"]:::component

      Buffer -->|"Manages"| Pages
      Pages -->|"Uses"| Indexes
      CatalogMgr -->|"Provides schema"| Pages
      CatalogMgr -->|"Provides schema"| Indexes
    end

    %% Cross-component connections (vertical, minimal)
    QCoreClient -->|"ExecutePlan"| Parser
    Executor -->|"Txn APIs"| TXN
    Executor -->|"Storage APIs"| Buffer
    TXN -->|"WAL/flush"| Buffer
    SchemaCtx -->|"Reads metadata"| CatalogMgr
    AUsers -->|"Integrates with"| IdP
    LLMClient -->|"Calls"| LLM
  end

  %% =========================
  %% Runtime sequences (compact, as notes)
  %% =========================
  subgraph "Key Runtime Flows (summary)"
    direction TB
    F1["Auth Flow: UI -> AuthSvc -> IdP -> token -> UI -> QuerySvc (token)"]:::note
    F2["SQL Flow: UI -> QuerySvc -> CoreQE <-> CoreTX <-> CoreST -> results"]:::note
    F3["NL Flow: UI -> QuerySvc -> NLSQL -> LLM -> SQL -> Core pipeline -> results + SQL used"]:::note
  end

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click WebUI "https://github.com/simphp5/veldb/tree/main/ui/web/"
  click UIComponents "https://github.com/simphp5/veldb/tree/main/ui/components/"
  click AuthSvc "https://github.com/simphp5/veldb/tree/main/api/auth/"
  click QuerySvc "https://github.com/simphp5/veldb/tree/main/api/query/"
  click NLSQL "https://github.com/simphp5/veldb/tree/main/ai/nl_to_sql/"
  click CoreQE "https://github.com/simphp5/veldb/tree/main/core/query_engine/"
  click CoreST "https://github.com/simphp5/veldb/tree/main/core/storage/"
  click CoreTX "https://github.com/simphp5/veldb/tree/main/core/transaction/"

  %% Bonus clicks for repo top-level mapping
  click VelDB "https://github.com/simphp5/veldb/tree/main/core/"
  click Mon "https://github.com/simphp5/veldb/tree/main/devops/"
  click F1 "https://github.com/simphp5/veldb/tree/main/docs/"
  click F2 "https://github.com/simphp5/veldb/tree/main/docs/"
  click F3 "https://github.com/simphp5/veldb/tree/main/docs/"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#F3F4F6,stroke:#374151,stroke-width:1px,color:#111827
  classDef system fill:#DBEAFE,stroke:#1D4ED8,stroke-width:2px,color:#0B1B3A
  classDef frontend fill:#BFDBFE,stroke:#2563EB,stroke-width:2px,color:#0B1B3A
  classDef service fill:#93C5FD,stroke:#1D4ED8,stroke-width:2px,color:#0B1B3A
  classDef core fill:#60A5FA,stroke:#1E40AF,stroke-width:2px,color:#0B1B3A
  classDef library fill:#86EFAC,stroke:#166534,stroke-width:2px,color:#052E16
  classDef component fill:#E0F2FE,stroke:#0284C7,stroke-width:1.5px,color:#0C4A6E
  classDef external fill:#FDBA74,stroke:#C2410C,stroke-width:2px,color:#4A1D0B
  classDef datastore fill:#E5E7EB,stroke:#111827,stroke-width:2px,color:#111827
  classDef note fill:#FEF3C7,stroke:#B45309,stroke-width:1.5px,color:#78350F
```
