CBDDC/docs/getting-started.md

Getting Started (v0.9.0)

Installation

CBDDC is available as a set of NuGet packages for .NET 8.0, .NET 6.0, and .NET Standard 2.0.

dotnet add package ZB.MOM.WW.CBDDC.Core
dotnet add package CBDDC.Network
dotnet add package ZB.MOM.WW.CBDDC.Persistence.Sqlite

Cloud & Enterprise Packages

For ASP.NET Core hosting and enterprise database support:

# ASP.NET Core hosting
dotnet add package ZB.MOM.WW.CBDDC.Hosting

# Entity Framework Core (SQL Server, MySQL, SQLite)
dotnet add package ZB.MOM.WW.CBDDC.Persistence.EntityFramework

# PostgreSQL with JSONB optimization
dotnet add package ZB.MOM.WW.CBDDC.Persistence.PostgreSQL

Requirements

• .NET 8.0+ Runtime (recommended) or .NET 6.0+
• SQLite (included via Microsoft.Data.Sqlite)
• PostgreSQL 12+ (optional, for PostgreSQL persistence)
• SQL Server 2016+ (optional, for SQL Server persistence)

Basic Usage

1. Initialize the Store

Use SqlitePeerStore for persistence. Supported on Windows, Linux, and macOS.

using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Sync;
using ZB.MOM.WW.CBDDC.Persistence.Sqlite;
using CBDDC.Network.Security;

// Choose conflict resolver (v0.6.0+)
var resolver = new RecursiveNodeMergeConflictResolver(); // OR LastWriteWinsConflictResolver()

var store = new SqlitePeerStore("Data Source=my-node.db", logger, resolver);
// Automatically creates tables on first run

2. Configure Networking (with Optional Security)

Use AddCBDDCNetwork extension method to register services.

var services = new ServiceCollection();
string myNodeId = "node-1";
int port = 5001;
string authToken = "my-secret-cluster-key";

services.AddSingleton<IPeerStore>(store);

// Optional: Enable encryption (v0.6.0+)
services.AddSingleton<IPeerHandshakeService, SecureHandshakeService>();

services.AddCBDDCNetwork(myNodeId, port, authToken);

3. Start the Node

var provider = services.BuildServiceProvider();
var node = provider.GetRequiredService<CBDDCNode>();

node.Start();

4. CRUD Operations

Interact with data using PeerDatabase.

var db = new PeerDatabase(store, "my-node-id"); // Node ID used for HLC clock
await db.InitializeAsync();

var users = db.Collection("users");

// Put
await users.Put("user-1", new { Name = "Alice", Age = 30 });

// Get
var user = await users.Get<User>("user-1");

// Query
var results = await users.Find<User>(u => u.Age > 20);

ASP.NET Core Deployment (v0.8.0+)

Single Cluster Mode (Recommended)

Perfect for production deployments with dedicated database servers:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Use PostgreSQL for production
builder.Services.AddCBDDCPostgreSql(
    builder.Configuration.GetConnectionString("CBDDC"));

// Configure single cluster
builder.Services.AddCBDDCHostingSingleCluster(options =>
{
    options.NodeId = "server-01";
    options.TcpPort = 5001;
});

var app = builder.Build();

app.MapHealthChecks("/health");
app.Run();

See Deployment Modes for deployment details.

What's New in v0.9.0

🚀 Production Enhancements

• Improved ASP.NET Core Sample: Enhanced error handling and better examples
• EF Core Stability: Fixed runtime issues for all persistence providers
• Sync Refinements: More reliable synchronization across hosted deployments

📸 Snapshots (v0.8.6)

• Fast Reconnection: Peers resume sync from the last known state
• Optimized Recovery: Prevents re-processing of already applied operations
• Automatic Management: Snapshot metadata tracked per peer

See CHANGELOG for complete version history.

What's New in v0.8.0

☁️ Cloud Infrastructure

• ASP.NET Core Hosting: Single-cluster deployment mode
• Multi-Database Support: SQL Server, PostgreSQL, MySQL, SQLite via EF Core
• PostgreSQL Optimization: JSONB storage with GIN indexes
• Shared-token Authentication: Secure controlled deployments
• Health Checks: Production monitoring and observability

Learn more about Cloud Deployment →

What's New in v0.7.0

📦 Efficient Networking

• Brotli Compression: Data is automatically compressed, significantly reducing bandwidth usage
• Protocol v4: Enhanced framing and security negotiation

What's New in v0.6.0

🔐 Secure Networking

Protect your data in transit with:

• ECDH key exchange
• AES-256-CBC encryption
• HMAC-SHA256 authentication

Learn more about Security →

🔀 Advanced Conflict Resolution

Choose your strategy:

• Last Write Wins - Simple, fast, timestamp-based
• Recursive Merge - Intelligent JSON merging with array ID detection

Learn more about Conflict Resolution →

🎯 Multi-Target Framework Support

• netstandard2.0 - Maximum compatibility
• net6.0 - Modern features
• net8.0 - Latest performance optimizations

Next Steps

• Architecture Overview - Understand HLC, Gossip Protocol, and mesh networking
• Persistence Providers - Choose the right database for your deployment
• Deployment Modes - Single-cluster deployment strategy
• Security Configuration - Encryption and authentication
• Conflict Resolution Strategies - LWW vs Recursive Merge
• Production Hardening - Best practices and monitoring
• API Reference - Complete API documentation