CBDDC/docs/architecture.md

Architecture & Concepts

Design Philosophy

CBDDC is designed for Local Area Networks (LAN) and Local-First scenarios.
It does not rely on a central master server. Every node is equal (Peer-to-Peer).

Target Deployment: Trusted LAN environments (offices, homes, private networks)
Cross-Platform: Windows, Linux, macOS (.NET 8.0+, with .NET 6.0 and .NET Standard 2.0 support)

HLC (Hybrid Logical Clock)

To resolve conflicts without a central authority, we use Hybrid Logical Clocks. This allows us to determine the "happened-before" relationship between events even if system clocks are slightly skewed. In case of concurrent edits, the "Last Write Wins" (LWW) policy based on HLC is applied.

Synchronization

Anti-Entropy

When two nodes connect, they exchange their latest HLC timestamps.

• If Node A is ahead of Node B, Node B "pulls" the missing operations from Node A.
• If Node B is ahead, Node A "pushes" its operations.

Gossip Protocol

Nodes discover each other via UDP Broadcast (LAN) and then form random TCP connections to gossip updates. This ensures that updates propagate exponentially through the network (Epidemic Algorithm).

Snapshots & Fast Recovery

To optimize reconnection, each node maintains a Snapshot of the last known state (Hash & Timestamp) for every peer.

• When re-connecting, nodes compare their snapshot state.
• If the chain hash matches, they only exchange the delta.
• This avoids re-processing the entire operation history and ensures efficient gap recovery.

Peer-Confirmed Oplog Pruning

CBDDC maintenance pruning now uses a two-cutoff model:

• Retention cutoff: derived from OplogRetentionHours (time-based policy).
• Confirmation cutoff: the oldest confirmation watermark across all active tracked peers and relevant source nodes.

The effective prune cutoff is:

• min(retention cutoff, confirmation cutoff) when confirmation data is complete.
• retention cutoff only when confirmation tracking is not configured or when there are no active tracked peers.
• no prune for that maintenance cycle when any active tracked peer is missing confirmation for any relevant source stream.

Key semantics:

• Relevant source streams are taken from the local non-default vector clock entries.
• A peer only gates pruning while it is active in peer tracking.
• Removing peer tracking excludes that peer from prune gating.
• Maintenance logs include explicit skip reasons when pruning is blocked (for example, missing confirmation for a tracked peer/source pair).

Security Disclaimer

::: warning FOR LAN USE ONLY CBDDC is designed for trusted Local Area Networks. :::

• P2P Mesh Mode: Designed for LAN/VPN use. Uses raw TCP and UDP broadcast. Not safe for public internet by default.
• ASP.NET Core Server: Designed for controlled server deployments. Supports standard HTTPS and hosted sync endpoints.
• Transport: Data is transmitted via raw TCP. There is NO Encryption (TLS/SSL) by default.
• Authentication: A basic "Shared Key" mechanism is implemented. Nodes must share the same AuthToken to sync.
• Authorization: Once authenticated, a node has full read/write access to all collections.

Recommendation:

• Use only within trusted private networks (LAN, VPN, or localhost)
• For internet deployment, implement TLS, proper authentication, and firewall rules
• Consider the production hardening features for resilience on LAN

Cross-Platform Support: Runs on Windows, Linux, and macOS with .NET 8.0+ (also supports .NET 6.0 and .NET Standard 2.0).