Initial import of the CBDDC codebase with docs and tests. Add a .NET-focused gitignore to keep generated artifacts out of source control.

2026-02-20 13:03:21 -05:00
commit 08bfc17218
218 changed files with 33910 additions and 0 deletions
--- a/src/ZB.MOM.WW.CBDDC.Core/README.md
+++ b/src/ZB.MOM.WW.CBDDC.Core/README.md
@@ -0,0 +1,105 @@
+# ZB.MOM.WW.CBDDC.Core
+
+Core abstractions and logic for **CBDDC**, a peer-to-peer data synchronization middleware for .NET.
+
+## What Is CBDDC?
+
+CBDDC is **not** a database — it's a sync layer that plugs into your existing data store (BLite) and enables automatic P2P replication across nodes in a mesh network. Your application reads and writes to its database as usual; CBDDC handles synchronization in the background.
+
+## What's In This Package
+
+- **Interfaces**: `IDocumentStore`, `IOplogStore`, `IVectorClockService`, `IConflictResolver`
+- **Models**: `OplogEntry`, `Document`, `HlcTimestamp`, `VectorClock`
+- **Conflict Resolution**: `LastWriteWinsConflictResolver`, `RecursiveNodeMergeConflictResolver`
+- **Production Features**: Document caching (LRU), offline queue, health monitoring, retry policies
+
+## Installation
+
+```bash
+# Pick a persistence provider
+dotnet add package ZB.MOM.WW.CBDDC.Persistence # Embedded document DB
+
+# Add networking
+dotnet add package ZB.MOM.WW.CBDDC.Network
+```
+
+## Quick Start
+
+```csharp
+// 1. Define your DbContext
+public class MyDbContext : CBDDCDocumentDbContext
+{
+    public DocumentCollection<string, User> Users { get; private set; }
+    public MyDbContext(string path) : base(path) { }
+}
+
+// 2. Create your DocumentStore (the sync bridge)
+public class MyDocumentStore : BLiteDocumentStore<MyDbContext>
+{
+    public MyDocumentStore(MyDbContext ctx, IPeerNodeConfigurationProvider cfg,
+        IVectorClockService vc, ILogger<MyDocumentStore>? log = null)
+        : base(ctx, cfg, vc, logger: log)
+    {
+        WatchCollection("Users", ctx.Users, u => u.Id);
+    }
+
+    protected override async Task ApplyContentToEntityAsync(
+        string collection, string key, JsonElement content, CancellationToken ct)
+    {
+        var user = content.Deserialize<User>()!;
+        user.Id = key;
+        var existing = _context.Users.Find(u => u.Id == key).FirstOrDefault();
+        if (existing != null) _context.Users.Update(user);
+        else _context.Users.Insert(user);
+        await _context.SaveChangesAsync(ct);
+    }
+    // ... implement other abstract methods
+}
+
+// 3. Register and use
+builder.Services.AddCBDDCCore()
+    .AddCBDDCBLite<MyDbContext, MyDocumentStore>(
+        sp => new MyDbContext("data.blite"))
+    .AddCBDDCNetwork<StaticPeerNodeConfigurationProvider>();
+```
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **CDC** | Change Data Capture — watches collections registered via `WatchCollection()` |
+| **Oplog** | Append-only hash-chained journal of changes per node |
+| **VectorClock** | Tracks causal ordering across the mesh |
+| **DocumentStore** | Your bridge between entities and the sync engine |
+
+## Architecture
+
+```
+Your App ? DbContext.SaveChangesAsync()
+               ?
+               ? CDC Trigger
+           DocumentStore.CreateOplogEntryAsync()
+               ?
+               ??? OplogEntry (hash-chained, HLC timestamped)
+               ??? VectorClockService.Update()
+                       ?
+                       ?
+               SyncOrchestrator (background)
+               ??? Push to peers
+               ??? Pull from peers ? ApplyBatchAsync
+```
+
+## Related Packages
+
+- **ZB.MOM.WW.CBDDC.Persistence** ï¿½ BLite embedded provider (.NET 10+)
+- **ZB.MOM.WW.CBDDC.Network** — P2P networking (UDP discovery, TCP sync, Gossip)
+
+## Documentation
+
+- **[Complete Documentation](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net)**
+- **[Sample Application](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/tree/main/samples/ZB.MOM.WW.CBDDC.Sample.Console)**
+- **[Integration Guide](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net#integrating-with-your-database)**
+
+## License
+
+MIT — see [LICENSE](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/blob/main/LICENSE)