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 and page the release maintainer listed in the active release PR

Architecture Overview

CBDD has four primary layers:

Storage and transaction engine (src/CBDD.Core/Storage, src/CBDD.Core/Transactions)
BSON serialization (src/CBDD.Bson)
Indexing and query execution (src/CBDD.Core/Indexing, src/CBDD.Core/Query)
Source-generated mapping (src/CBDD.SourceGenerators)

Detailed architecture material:

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

Clone the repository.

git clone https://gitea.dohertylan.com/dohertj2/CBDD.git
cd CBDD

Expected outcome: local repository checkout with CBDD.slnx present.

Restore dependencies.

dotnet restore

Expected outcome: restore completes without package errors.

Build the solution.

dotnet build CBDD.slnx -c Release

Expected outcome: solution builds without compiler errors.

Run tests.

dotnet test CBDD.slnx -c Release

Expected outcome: all tests pass.

Run the full repository fitness check.

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:

dotnet format --verify-no-changes
dotnet build -t:Rebuild
dotnet test
bash scripts/coverage-check.sh

Optional full gate:

bash scripts/fitness-check.sh

Deployment And Rollback

CBDD is released as an internal package.

Deployment workflow: docs/deployment.md
Rollback workflow: docs/deployment.md#rollback-procedure

Operations And Incident Response

Operational procedures, diagnostics, and escalation are documented in:

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.
Role and approval requirements are defined in docs/access.md.

Troubleshooting

Common issues and remediation:

Build/test environment failures: docs/troubleshooting.md#build-and-test-failures
Data-file recovery procedures: docs/troubleshooting.md#data-file-and-recovery-issues
Query/index behavior verification: 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
Major feature inventory: docs/features/README.md
Architecture decisions: docs/adr/0001-storage-engine-and-source-generation.md