CBDD/docs/architecture.md

Architecture

System Context

CBDD is an embedded database library consumed in-process by .NET applications. The host application owns process lifecycle, filesystem placement, and operational policy.

External dependencies:

• .NET runtime and SDK
• Local filesystem
• Optional CI and package registry for build/release

Containers And Major Components

1. CBDD.Core

• Owns storage engine, transaction protocol, WAL, indexing, query planning, and CDC plumbing.

2. CBDD.Bson

• Owns BSON document model and span-based serialization/deserialization primitives.

3. CBDD.SourceGenerators

• Generates mapping code at compile time for entity serialization and collection initialization.

4. Consumer application

• Defines entities, DocumentDbContext subclasses, and operational behavior.

Data Flow

1. Consumer invokes collection API through DocumentDbContext.
2. Mapper layer serializes entities to BSON via generated mappers.
3. Storage engine writes page data and WAL entries.
4. Index subsystem updates primary and secondary indexes.
5. Transaction commit persists durable state and emits CDC notifications where enabled.
6. Query path evaluates expression plans and uses indexes or scan fallback.

Reliability Model

• Write-ahead logging enforces durability before logical commit completion.
• Snapshot isolation supports concurrent reads with transactional correctness.
• Recovery logic replays WAL on restart to restore committed state.

Cross References

• Operational procedures: runbook.md
• Deployment and rollback: deployment.md
• Security controls: security.md
• Detailed protocol reference: ../RFC.md