ChatCore.RealTime.SignalR 1.0.1

ChatCore.NET

A modular, scalable, SignalR-powered chat framework for .NET

🎯 Overview

ChatCore.NET is an enterprise-grade chat engine for .NET 8 applications. It provides a clean, pluggable abstraction over real-time communication with support for 1:1 and group conversations, read receipts, presence tracking, and horizontal scaling.

✨ Features

• Modular Architecture — clean separation of concerns with pluggable storage and transport layers
• Real-Time Delivery — built-in SignalR integration with automatic sender exclusion
• Multi-Tenancy Ready — tenant isolation enforced at every layer including composite foreign keys
• Message Ordering Guarantee — atomic sequence-number assignment per conversation
• Read Receipts — high-water-mark tracking per user per conversation
• Presence Tracking — online/offline status with multi-connection support
• Soft Deletes — message content replaced with [deleted], record retained for audit
• Idempotency — prevent duplicate sends with a client-supplied idempotency key
• Interceptor Pipeline — middleware-style hooks before and after every send
• Seek-based Pagination — cursor pagination on sequence numbers — no OFFSET scans
• Global Exception Handling — structured JSON error responses from a single middleware

📦 Packages

🚀 Quick Start

1. Install

dotnet add package ChatCore.AspNetCore

2. Register services

// Program.cs
builder.Services
    .AddChatCore()
    .UseEntityFramework(connectionString)
    .UseSignalR()
    .Build();

3. Map the hub and middleware

app.UseChatCoreExceptionHandler();  // global exception handler — register first
app.UseCors("ChatCoreCors");        // required for browser SignalR clients
app.MapChatHub("/hubs/chat");

4. Send a message

public class MessagesController : ControllerBase
{
    private readonly IChatEngine _engine;
    public MessagesController(IChatEngine engine) => _engine = engine;

    [HttpPost("{conversationId}/messages")]
    public async Task<IActionResult> Send(Guid conversationId, [FromBody] SendBody body)
    {
        var result = await _engine.SendAsync(new ChatMessageRequest
        {
            ConversationId = conversationId,
            SenderId       = User.GetUserId(),
            TenantId       = User.GetTenantId(),
            Content        = body.Content,
            IdempotencyKey = body.IdempotencyKey
        });
        return result.IsSuccess ? Ok(result.Data) : BadRequest(result.Error);
    }
}

5. Connect from JavaScript

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/hubs/chat", { accessTokenFactory: () => yourJwtToken })
    .withAutomaticReconnect()
    .build();

connection.on("MessageReceived", (message) => console.log(message));

await connection.start();
await connection.invoke("JoinConversation", conversationId);
await connection.invoke("SendMessage", conversationId, "Hello!", tenantId);

📚 Documentation

Full documentation is in the docs/ folder:

🔐 Design Principles

1. Storage Agnostic — swap storage behind an interface without touching the engine
2. Transport Agnostic — SignalR today, anything tomorrow
3. Multi-Tenant by Default — every entity carries TenantId, enforced at the database FK level
4. Ordering Guarantee — atomic sequence numbers per conversation
5. Scalability First — seek pagination, stateless design, Redis backplane support
6. Extensible — interceptor pipeline for content filtering, audit logging, rate limiting
7. Test Friendly — interface-driven, 70+ tests across unit and integration suites

📝 Roadmap

• Core abstractions and domain models
• ChatEngine with full send / read / paginate / delete
• Entity Framework Core persistence layer
• SignalR transport with correct sender exclusion
• ASP.NET Core integration and DI builder
• Unit and integration tests (70+ tests)
• Global exception middleware
• NuGet package release
• Redis backplane support
• Message encryption layer
• Webhook support for external integrations
• Multi-tenant admin dashboard

🤝 Contributing

Contributions are welcome! See docs/10-contributing-guidelines.md for the full guide.

📄 License

MIT — see LICENSE for details.

👨‍💻 Author

CalebTek — GitHub