# 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 `/Users/dohertj2/Desktop/CBDD/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 (`/Users/dohertj2/Desktop/CBDD/src/CBDD.Core/Storage`, `/Users/dohertj2/Desktop/CBDD/src/CBDD.Core/Transactions`)
2. BSON serialization (`/Users/dohertj2/Desktop/CBDD/src/CBDD.Bson`)
3. Indexing and query execution (`/Users/dohertj2/Desktop/CBDD/src/CBDD.Core/Indexing`, `/Users/dohertj2/Desktop/CBDD/src/CBDD.Core/Query`)
4. Source-generated mapping (`/Users/dohertj2/Desktop/CBDD/src/CBDD.SourceGenerators`)

Detailed architecture material:
- `/Users/dohertj2/Desktop/CBDD/docs/architecture.md`
- `/Users/dohertj2/Desktop/CBDD/RFC.md`
- `/Users/dohertj2/Desktop/CBDD/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: `/Users/dohertj2/Desktop/CBDD/docs/deployment.md`
- Rollback workflow: `/Users/dohertj2/Desktop/CBDD/docs/deployment.md#rollback-procedure`

## Operations And Incident Response

Operational procedures, diagnostics, and escalation are documented in:

- `/Users/dohertj2/Desktop/CBDD/docs/runbook.md`
- `/Users/dohertj2/Desktop/CBDD/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 `/Users/dohertj2/Desktop/CBDD/docs/security.md`.
- Role and approval requirements are defined in `/Users/dohertj2/Desktop/CBDD/docs/access.md`.

## Troubleshooting

Common issues and remediation:

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