Architecture

Architecture#

DBLayer is layered so each concern stays explicit: query composition, connection lifecycle, security validation, and observability are separate modules that cooperate through events and typed payloads.

Core Components#

  • DB facade: static entrypoint.

  • TableRepository: repository-oriented static adapter over repository/builder/facade.

  • Connection: PDO lifecycle, driver, execution controls.

  • QueryBuilder: fluent SQL builder.

  • Repository: table-oriented abstraction.

Responsibility Boundaries#

These components are intentionally separate:

  • DB is process-level orchestration state (connection registry, transaction entrypoints, pooling, telemetry/profiler wiring).

  • QueryBuilder is per-query mutable state (clauses, bindings, SQL payload).

  • Repository is per-table policy state (tenant scope, soft deletes, optimistic locking, casts, hooks, default ordering).

Keeping them distinct prevents a single “god class” that mixes infrastructure and table business rules.

Data Flow#

Typical request flow:

  1. Application code calls DB::table() or DB::repository().

  2. Builder/repository creates query payload + bindings.

  3. Connection validates and executes through driver/compiler.

  4. Events are emitted for logging/profiling/telemetry hooks.

  5. Result processors/casts adapt output for caller usage.

Layer Lifecycles#

  • DB static state usually lives for the process/request lifetime.

  • QueryBuilder instances are short-lived and discarded after query use.

  • Repository instances are reusable per table policy context.

This lifecycle mismatch is the main reason DBLayer does not collapse these three concepts into one class.

Driver Stack#

  • MySQL, PostgreSQL, SQLite drivers.

  • Grammar/compiler per dialect.

  • Capabilities flags for feature checks.

Dialect-sensitive features (for example RETURNING or lock syntax) are resolved through this layer, not through conditional logic in application code.

Runtime Modules#

  • Transactions and savepoints

  • Read replicas and strategies

  • Pooling and health checks

  • Security validation

  • Events, logger, profiler, telemetry

  • Caching strategies

Design Intent#

  • Keep raw SQL accessible when needed.

  • Keep fluent APIs predictable and composable.

  • Keep infrastructure concerns opt-in (logger/profiler/telemetry).

  • Keep safety checks centrally configurable.

  • Keep domain/table rules reusable without forcing full ORM-style models.