How simphp5/veldb works
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