133 lines
4.5 KiB
Markdown
Executable File
133 lines
4.5 KiB
Markdown
Executable File
# CBDD
|
|
|
|
CBDD is an embedded, document-oriented database engine for .NET 10. It targets internal platform teams that need predictable ACID behavior, low-latency local persistence, and typed access patterns without running an external database server.
|
|
|
|
## Purpose And Business Context
|
|
|
|
CBDD provides a local data layer for services and tools that need transactional durability, deterministic startup, and high-throughput reads/writes. The primary business outcome is reducing operational overhead for workloads that do not require a networked database cluster.
|
|
|
|
## Ownership And Support
|
|
|
|
- Owning team: CBDD maintainers (repository owner: `@dohertj2`)
|
|
- Primary support path: open a Gitea issue in this repository with labels `incident` or `bug`
|
|
- Escalation path: follow [`docs/runbook.md`](docs/runbook.md) and page the release maintainer listed in the active release PR
|
|
|
|
## Architecture Overview
|
|
|
|
CBDD has four primary layers:
|
|
|
|
1. Storage and transaction engine (`src/CBDD.Core/Storage`, `src/CBDD.Core/Transactions`)
|
|
2. BSON serialization (`src/CBDD.Bson`)
|
|
3. Indexing and query execution (`src/CBDD.Core/Indexing`, `src/CBDD.Core/Query`)
|
|
4. Source-generated mapping (`src/CBDD.SourceGenerators`)
|
|
|
|
Detailed architecture material:
|
|
- [`docs/architecture.md`](docs/architecture.md)
|
|
- [`RFC.md`](RFC.md)
|
|
- [`C-BSON.md`](C-BSON.md)
|
|
|
|
## Prerequisites
|
|
|
|
- .NET SDK 10.x
|
|
- Bash (for repository scripts)
|
|
- Read/write permissions for the local working directory
|
|
- Gitea access for pull requests and release publishing
|
|
|
|
## Setup And Local Run
|
|
|
|
1. Clone the repository.
|
|
```bash
|
|
git clone https://gitea.dohertylan.com/dohertj2/CBDD.git
|
|
cd CBDD
|
|
```
|
|
Expected outcome: local repository checkout with `CBDD.slnx` present.
|
|
|
|
2. Restore dependencies.
|
|
```bash
|
|
dotnet restore
|
|
```
|
|
Expected outcome: restore completes without package errors.
|
|
|
|
3. Build the solution.
|
|
```bash
|
|
dotnet build CBDD.slnx -c Release
|
|
```
|
|
Expected outcome: solution builds without compiler errors.
|
|
|
|
4. Run tests.
|
|
```bash
|
|
dotnet test CBDD.slnx -c Release
|
|
```
|
|
Expected outcome: all tests pass.
|
|
|
|
5. Run the full repository fitness check.
|
|
```bash
|
|
bash scripts/fitness-check.sh
|
|
```
|
|
Expected outcome: format, build, tests, coverage threshold, and package checks complete.
|
|
|
|
## Configuration And Secrets
|
|
|
|
- Default local usage requires only a filesystem path for the database file.
|
|
- Do not commit secrets in source, test fixtures, benchmark assets, or `.env` files.
|
|
- If publishing packages, keep feed credentials in CI secrets or local keychain-backed credential storage.
|
|
- Store environment-specific values outside the repository and inject them at runtime.
|
|
|
|
## Build, Test, And Quality Gates
|
|
|
|
Required pre-merge commands:
|
|
|
|
```bash
|
|
dotnet format --verify-no-changes
|
|
dotnet build -t:Rebuild
|
|
dotnet test
|
|
bash scripts/coverage-check.sh
|
|
```
|
|
|
|
Optional full gate:
|
|
|
|
```bash
|
|
bash scripts/fitness-check.sh
|
|
```
|
|
|
|
## Deployment And Rollback
|
|
|
|
CBDD is released as an internal package.
|
|
|
|
- Deployment workflow: [`docs/deployment.md`](docs/deployment.md)
|
|
- Rollback workflow: [`docs/deployment.md#rollback-procedure`](docs/deployment.md#rollback-procedure)
|
|
|
|
## Operations And Incident Response
|
|
|
|
Operational procedures, diagnostics, and escalation are documented in:
|
|
|
|
- [`docs/runbook.md`](docs/runbook.md)
|
|
- [`docs/troubleshooting.md`](docs/troubleshooting.md)
|
|
|
|
## Security And Compliance Posture
|
|
|
|
- CBDD relies on host and process-level access controls.
|
|
- Sensitive payload classification and handling requirements are defined in [`docs/security.md`](docs/security.md).
|
|
- Role and approval requirements are defined in [`docs/access.md`](docs/access.md).
|
|
|
|
## Troubleshooting
|
|
|
|
Common issues and remediation:
|
|
|
|
- Build/test environment failures: [`docs/troubleshooting.md#build-and-test-failures`](docs/troubleshooting.md#build-and-test-failures)
|
|
- Data-file recovery procedures: [`docs/troubleshooting.md#data-file-and-recovery-issues`](docs/troubleshooting.md#data-file-and-recovery-issues)
|
|
- Query/index behavior verification: [`docs/troubleshooting.md#query-and-index-issues`](docs/troubleshooting.md#query-and-index-issues)
|
|
|
|
## Change Governance
|
|
|
|
- Use feature branches from `main`.
|
|
- Open pull requests with at least one reviewer approval before merge.
|
|
- Keep release notes in pull request descriptions and tagged release notes.
|
|
- Run documented quality gates before requesting review.
|
|
|
|
## Documentation Index
|
|
|
|
- Documentation home: [`docs/README.md`](docs/README.md)
|
|
- Major feature inventory: [`docs/features/README.md`](docs/features/README.md)
|
|
- Architecture decisions: [`docs/adr/0001-storage-engine-and-source-generation.md`](docs/adr/0001-storage-engine-and-source-generation.md)
|