AppXDev.SyncEntityFramework 0.6.1

AppXDev.SyncEntityFramework

A bidirectional Entity Framework sync framework for distributed retail systems. Synchronize data between a central server and multiple store locations using SQL Server and message-based communication.

🚀 Features

• Bidirectional Sync: Push and pull changes between Central HQ and Store locations.
• Conflict Resolution: Configurable strategies (LastWriteWins, Merge, Manual).
• Resilient Architecture: Handles offline scenarios with local queuing and retry policies.
• Real-time Dashboard: Visual monitoring of data propagation across nodes.
• EF Core Integration: Seamlessly hooks into EF Core SaveChanges for automatic change tracking.
• Docker Ready: Full environment orchestration with Docker Compose.

🏁 Quick Start (Run the Demo)

The easiest way to see the framework in action is to run the full Docker environment, which spins up:

1. Central API: The HQ server.
2. Store Agents (A & B): Two independent store nodes.
3. Dashboard: A Blazor UI to visualize and manipulate data.
4. Infrastructure: SQL Server and RabbitMQ.

Prerequisites

• Docker Desktop
• .NET 9.0 SDK (for local development)

Steps

1. Clone the repository

   git clone https://github.com/qdev89/AppXDev.SyncEntityFramework.git
   cd AppXDev.SyncEntityFramework
   

2. Start the Environment

   docker-compose up --build
   

   Wait for all services to start. SQL Server initialization may take a minute.

3. Access the Dashboard Open your browser to: http://localhost:5200

🖥️ Using the Dashboard

The Sync Dashboard allows you to simulate real-world retail scenarios:

1. Visualizing Sync

• Three Columns: Represents the databases of Central Server, Store A, and Store B.
• Auto-Refresh: The UI updates every 10 seconds to show data propagating between nodes.
• Status Indicators:
  • <span style="color:green">Green Badge</span>: High Stock
  • <span style="color:orange">Yellow Badge</span>: Low Stock
  • <span style="color:red">Red Badge</span>: Out of Stock

2. Simulating Actions

• Add to Central: Simulates an HQ product launch. Watch it appear in Store A and Store B after a few seconds.
• Add to Store A: Simulates a local store creation. It will sync to Central, then down to Store B.
• Reset / Clean Up: Wipes all data from all databases to start fresh.

📦 Installation (For Developers)

To use the SDK in your own project:

# Full SDK
dotnet add package AppXDev.SyncEntityFramework

# Or individual packages
dotnet add package AppXDev.SyncEntityFramework.Domain
dotnet add package AppXDev.SyncEntityFramework.Application

1. Define Sync Entities

Inherit from SyncEntity to enable tracking.

using AppXDev.Sync.Domain.Entities;

[SyncEntity(ConflictStrategy.LastWriteWins, SyncPriority.High)]
public class Product : SyncEntity
{
    public string Name { get; set; }
    public decimal Price { get; set; }
}

2. Register Services

In Program.cs:

// Add Core Sync Services
builder.Services.AddScoped<IChangeTracker, EfCoreChangeTracker>();
builder.Services.AddScoped<ISyncEngine, SyncService>();

// Add Interceptor for Auto-Tracking
builder.Services.AddSingleton<SyncSaveChangesInterceptor>(sp => 
    new SyncSaveChangesInterceptor("STORE-001"));

// Register DbContext with Interceptor
builder.Services.AddDbContext<AppDbContext>((sp, options) => {
    options.UseSqlServer("...");
    options.AddInterceptors(sp.GetRequiredService<SyncSaveChangesInterceptor>());
});

🏗️ Architecture

The solution follows a Hub-and-Spoke architecture:

graph TD
    Central[Central API]
    StoreA[Store A Agent]
    StoreB[Store B Agent]
    RabbitMQ((RabbitMQ))
    
    StoreA <-->|HTTP Pull/Push| Central
    StoreB <-->|HTTP Pull/Push| Central
    Central -.->|Notify| RabbitMQ
    RabbitMQ -.->|Wake Up| StoreA
    RabbitMQ -.->|Wake Up| StoreB

• Central API: The source of truth. Exposes endpoints for Pull (get changes) and Push (receive changes).
• Store Agent: A background worker that periodically polls Central for updates and pushes local changes.
• SyncChangeApplicator: A service that deserializes JSON change sets and applies them to the actual Entity tables.

📂 Project Structure

• src/AppXDev.Sync.Domain: Core entities and interfaces.
• src/AppXDev.Sync.Application: Business logic and sync orchestration.
• src/AppXDev.Sync.Infrastructure: EF Core and RabbitMQ implementations.
• src/AppXDev.Sync.Central.Api: The HQ Web API.
• src/AppXDev.Sync.Store.Agent: The background worker for stores.
• src/AppXDev.Sync.Demo.Dashboard: Blazor UI for visualization.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.