mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 14:25:02 +00:00
johndoe6345789
49f40177b5
README.md
LICENSE
AGENTS.md
api/ # Language-agnostic contract (source of truth)
schema/
entities/ # Entity definitions (conceptual models)
user.yaml
session.yaml
...
operations/ # CRUD + domain operations (semantic, not SQL)
user.ops.yaml
...
errors.yaml # Standard error codes (conflict, not_found, etc.)
capabilities.yaml # Feature flags per backend (tx, joins, ttl, etc.)
idl/
dbal.proto # Optional: RPC/IPC contract if needed
dbal.fbs # Optional: FlatBuffers schema if you prefer
versioning/
compat.md # Compatibility rules across TS/C++
common/ # Shared test vectors + fixtures + golden results
fixtures/
seed/
datasets/
golden/
query_results/
contracts/
conformance_cases.yaml
ts/ # Development implementation in TypeScript
package.json
tsconfig.json
src/
index.ts # Public entrypoint (creates client)
core/
client.ts # DBAL client facade
types.ts # TS types mirroring api/schema
errors.ts # Error mapping to api/errors.yaml
validation/ # Runtime validation (zod/io-ts/etc.)
input.ts
output.ts
capabilities.ts # Capability negotiation
telemetry/
logger.ts
metrics.ts
tracing.ts
adapters/ # Backend implementations (TS)
prisma/
index.ts
prisma_client.ts # Wraps Prisma client (server-side only)
mapping.ts # DB <-> entity mapping, select shaping
migrations/ # Optional: Prisma migration helpers
sqlite/
index.ts
sqlite_driver.ts
schema.ts
migrations/
mongodb/
index.ts
mongo_driver.ts
schema.ts
query/ # Query builder / AST (no backend leakage)
ast.ts
builder.ts
normalize.ts
optimize.ts
runtime/
config.ts # DBAL config (env, URLs, pool sizes)
secrets.ts # Secret loading boundary (server-only)
util/
assert.ts
retry.ts
backoff.ts
time.ts
tests/
unit/
integration/
conformance/ # Runs common/contract vectors on TS adapters
harness/
setup.ts
cpp/ # Production implementation in C++
CMakeLists.txt
include/
dbal/
dbal.hpp # Public API
client.hpp # Facade
types.hpp # Entity/DTO types
errors.hpp
capabilities.hpp
telemetry.hpp
query/
ast.hpp
builder.hpp
normalize.hpp
adapters/
adapter.hpp # Adapter interface
sqlite/
sqlite_adapter.hpp
mongodb/
mongodb_adapter.hpp
prisma/
prisma_adapter.hpp # Usually NOT direct; see note below
util/
expected.hpp
result.hpp
uuid.hpp
src/
client.cpp
errors.cpp
capabilities.cpp
telemetry.cpp
query/
ast.cpp
builder.cpp
normalize.cpp
adapters/
sqlite/
sqlite_adapter.cpp
sqlite_pool.cpp
sqlite_migrations.cpp
mongodb/
mongodb_adapter.cpp
mongo_pool.cpp
prisma/
prisma_adapter.cpp # See note below (often an RPC bridge)
util/
uuid.cpp
backoff.cpp
tests/
unit/
integration/
conformance/ # Runs common/contract vectors on C++ adapters
harness/
main.cpp
backends/ # Backend-specific assets not tied to one lang
sqlite/
schema.sql
migrations/
mongodb/
indexes.json
prisma/
schema.prisma
migrations/
tools/ # Codegen + build helpers (prefer Python)
codegen/
gen_types.py # api/schema -> ts/core/types.ts and cpp/types.hpp
gen_errors.py
gen_capabilities.py
conformance/
run_all.py # runs TS + C++ conformance suites
dev/
lint.py
format.py
scripts/ # Cross-platform entrypoints (Python per your pref)
build.py
test.py
conformance.py
package.py
dist/ # Build outputs (gitignored)
.github/
workflows/
ci.yml
.gitignore
.editorconfig
4.2 KiB
4.2 KiB
DBAL Project Structure
This directory contains the Database Abstraction Layer for MetaBuilder.
Quick Links
- Main README - Overview and architecture
- Agent Guide - For AI agents and automated tools
- Spark Integration - GitHub Spark deployment guide
- TypeScript Implementation - TS development guide
- C++ Implementation - C++ production guide
Directory Structure
dbal/
├── README.md # Main documentation
├── LICENSE # MIT License
├── AGENTS.md # Agent development guide
├── .gitignore # Git ignore rules
│
├── api/ # Language-agnostic API definition
│ ├── schema/ # Entity and operation schemas
│ │ ├── entities/ # Entity definitions (YAML)
│ │ ├── operations/ # Operation definitions (YAML)
│ │ ├── errors.yaml # Error codes and handling
│ │ └── capabilities.yaml # Backend capability matrix
│ └── versioning/
│ └── compat.md # Compatibility rules
│
├── common/ # Shared resources
│ ├── contracts/ # Conformance test definitions
│ ├── fixtures/ # Test data
│ └── golden/ # Expected test results
│
├── ts/ # TypeScript implementation
│ ├── package.json
│ ├── tsconfig.json
│ ├── src/
│ │ ├── index.ts # Public API
│ │ ├── core/ # Core abstractions
│ │ ├── adapters/ # Backend adapters
│ │ ├── query/ # Query builder
│ │ └── runtime/ # Config and telemetry
│ └── tests/
│
├── cpp/ # C++ implementation
│ ├── CMakeLists.txt
│ ├── include/dbal/ # Public headers
│ ├── src/ # Implementation
│ └── tests/
│
├── backends/ # Backend-specific assets
│ ├── prisma/
│ │ └── schema.prisma # Prisma schema
│ └── sqlite/
│ └── schema.sql # SQLite schema
│
├── tools/ # Build and dev tools
│ ├── codegen/ # Type generation scripts
│ └── conformance/ # Test runners
│
├── scripts/ # Entry point scripts
│ ├── build.py # Build all implementations
│ ├── test.py # Run all tests
│ └── conformance.py # Run conformance tests
│
└── docs/ # Additional documentation
└── SPARK_INTEGRATION.md # GitHub Spark guide
Quick Start
Generate Types
python tools/codegen/gen_types.py
Build Everything
python scripts/build.py
Run Tests
python scripts/test.py
Run Conformance Tests
python scripts/conformance.py
Development Workflow
- Define schema in
api/schema/entities/andapi/schema/operations/ - Generate types with
python tools/codegen/gen_types.py - Implement adapters in
ts/src/adapters/andcpp/src/adapters/ - Write tests in
common/contracts/ - Build with
python scripts/build.py - Test with
python scripts/test.py - Deploy following
docs/SPARK_INTEGRATION.md
Key Concepts
- Language Agnostic: API defined in YAML, implementations in TS and C++
- Security First: C++ daemon isolates credentials, enforces ACL
- Development Speed: TypeScript for rapid iteration
- Production Security: C++ for hardened production deployments
- Conformance: Both implementations must pass identical tests
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: docs.metabuilder.io/dbal