# 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)