mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 22:34:56 +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
121 lines
4.2 KiB
Markdown
121 lines
4.2 KiB
Markdown
# DBAL Project Structure
|
|
|
|
This directory contains the Database Abstraction Layer for MetaBuilder.
|
|
|
|
## Quick Links
|
|
|
|
- [Main README](README.md) - Overview and architecture
|
|
- [Agent Guide](AGENTS.md) - For AI agents and automated tools
|
|
- [Spark Integration](docs/SPARK_INTEGRATION.md) - GitHub Spark deployment guide
|
|
- [TypeScript Implementation](ts/README.md) - TS development guide
|
|
- [C++ Implementation](cpp/README.md) - 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
|
|
|
|
```bash
|
|
python tools/codegen/gen_types.py
|
|
```
|
|
|
|
### Build Everything
|
|
|
|
```bash
|
|
python scripts/build.py
|
|
```
|
|
|
|
### Run Tests
|
|
|
|
```bash
|
|
python scripts/test.py
|
|
```
|
|
|
|
### Run Conformance Tests
|
|
|
|
```bash
|
|
python scripts/conformance.py
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
1. **Define schema** in `api/schema/entities/` and `api/schema/operations/`
|
|
2. **Generate types** with `python tools/codegen/gen_types.py`
|
|
3. **Implement adapters** in `ts/src/adapters/` and `cpp/src/adapters/`
|
|
4. **Write tests** in `common/contracts/`
|
|
5. **Build** with `python scripts/build.py`
|
|
6. **Test** with `python scripts/test.py`
|
|
7. **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](https://github.com/yourorg/metabuilder/issues)
|
|
- Discussions: [GitHub Discussions](https://github.com/yourorg/metabuilder/discussions)
|
|
- Documentation: [docs.metabuilder.io/dbal](https://docs.metabuilder.io/dbal)
|