Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Features.Notifications

Notification bus implementation for Eltheon. It publishes operational notifications to registered sinks and exposes the neutral IEltheonNotificationPublisher port from Core.Abstractions.

This package no longer depends on SignalR, Metrik, or Events. Realtime delivery, metrics, and lifecycle events are optional integrations through Core.Abstractions ports.

Install

dotnet add package Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Features.Notifications

Building Blocks

• NotificationMessage describes the internal notification payload.
• NotificationScope, NotificationSeverity, and NotificationCategoryKeys remain feature-local compatibility types.
• INotificationPublisher is the feature-local compatibility publisher contract.
• IEltheonNotificationPublisher accepts both the existing compatibility overload and structured message/options requests from Core.Abstractions.
• NotificationBus evaluates policy-selected channel providers for structured and compatibility publications when policy/provider services are registered; sink fan-out remains its fallback for minimal registrations.
• NotificationChannelProviderRegistry discovers IEltheonNotificationChannelProvider registrations through DI and rejects duplicate channel keys.
• NotificationDeliveryDecisionService resolves persistence mode, effective channels, preference overrides, deduplication/coalescing values and audit intent.
• InAppNotificationChannelProvider delegates persistence to the optional host INotificationInboxStore.
• RealtimeNotificationSink supports minimal fallback registrations; RealtimeNotificationChannelProvider forwards policy-selected publications through IEltheonRealtimeNotificationPublisher.

DI Setup

builder.Services.AddEltheonNotifications();

To add realtime delivery through SignalR, register the SignalR package's publisher and then add the notification bridge:

builder.Services.AddSignalRRealtimeNotificationPublisher();
builder.Services.AddNotificationSignalRBridge();

AddNotificationSignalRBridge() no longer references SignalR directly. It registers the legacy sink and structured realtime provider against IEltheonRealtimeNotificationPublisher; SignalR is only one possible implementation of that port.

For Admin and User notification surfaces, register the Razor application part on both page and MVC builders:

builder.Services.AddRazorPages().AddEltheonNotificationsApplicationPart();
builder.Services.AddMvc().AddEltheonNotificationsApplicationPart();

The package owns /Admin/Notifications, /User/Notifications, their API controllers, typed permission declarations, navigation contributions and EltheonJS clients. Hosts provide INotificationUiStore when their persistence and identity implementation is template-owned.

INotificationUiStore supplies the RCL with inbox paging, unread/read/dismissed state, top-header data, user channel preferences and administrative policy snapshots. The built-in Template adapter persists read and dismissed as distinct per-user states; marking a message read does not remove it from the user's read/all views.

Inbox and top-header reads are windowed for large persisted histories. NotificationInboxQueryResponse.TotalIsExact and UnreadCountIsExact indicate whether a returned count is complete or a bounded UI preview; clients must use HasMore for forward paging when TotalIsExact is false. The top-header and cockpit show bounded unread values with a +/9+ indicator rather than issuing full-history counts. The built-in Template adapter indexes CreatedAtUtc for recent-item and recent-analytics queries.

Key user endpoints are:

GET  /api/v1/user/notifications?status=unread|read|dismissed|all
POST /api/v1/user/notifications/{id}/read
POST /api/v1/user/notifications/read-all
POST /api/v1/user/notifications/{id}/dismiss
GET  /api/v1/user/notifications/preferences?channel=mail
PUT  /api/v1/user/notifications/preferences/{categoryId}
GET  /api/v1/user/notifications/top-header

The Admin API exposes equivalent inbox/top-header state operations plus cockpit, channel status, policy update, delivery evaluation and test-publication actions. Admin actions are separated through the typed View, Manage, SendTest, Diagnostics, Channels and Preferences permission keys. The template cockpit adapter derives persisted, coalesced and top-category counters from NotificationEvents; the feature-owned NotificationOperationalMetrics supplies delivered, suppressed, failed and deduplicated provider outcomes observed during the current host process. The cockpit exposes the runtime counter start time so those volatile values are not mistaken for persisted history after a restart.

The Admin cockpit is organized into Overview, Delivery policies, Channels, Test & Diagnostics, and Messages tabs. Its polling refresh updates live snapshot regions and charts only; policy and diagnostic form controls remain stable while administrators edit them. Category and channel inputs are populated from the existing settings/channel surfaces, and delivery evaluation displays the effective policy decision without publishing a notification. A non-persistent category configured without channels is disabled for delivery, which allows administrators to turn off noisy realtime-only categories such as service.lifecycle.

Admin test publications that explicitly select mail include the signed-in administrator as a concrete recipient, so the host mail adapter can queue a test email when policy permits the mail channel. Template mail delivery renders the dedicated Notifications.Message email template through the Email feature queue, exposing title, body, category and severity placeholders for theme/override customization. Provider health checks report configured in-app, realtime and template mail availability in the Channels tab; health is configuration/registration state, not proof of an external mail server round trip.

Publishing

Feature code should prefer the neutral publisher when it does not need notification implementation details:

public sealed class DeploymentService
{
    private readonly IEltheonNotificationPublisher _publisher;

    public DeploymentService(IEltheonNotificationPublisher publisher)
    {
        _publisher = publisher;
    }

    public Task NotifyDeploymentAsync(CancellationToken ct)
    {
        return _publisher.PublishAsync(
            title: "Deployment",
            message: "A new build is live.",
            scope: EltheonNotificationScope.Admin | EltheonNotificationScope.User,
            severity: EltheonNotificationSeverity.Success,
            category: EltheonNotificationCategoryKeys.General,
            cancellationToken: ct);
    }
}

Consumers inside the Notifications feature can still use INotificationPublisher and NotificationMessage directly.

Structured publishing is also available to cross-feature consumers:

await _publisher.PublishAsync(
    new EltheonNotificationMessage
    {
        Title = "Deployment",
        Message = "A new build is live.",
        CategoryKey = EltheonNotificationCategoryKeys.General,
        Scope = EltheonNotificationScope.Admin,
        Targets = [EltheonNotificationTarget.Role("Admin")]
    },
    new EltheonNotificationPublishOptions
    {
        PreferredChannels = [EltheonNotificationChannel.InApp, EltheonNotificationChannel.Realtime]
    },
    ct);

When policy/provider services are registered, the bus evaluates target-aware delivery policy for both structured messages and existing publisher overloads. Default informational/success messages are realtime-only; warnings/errors default to inbox plus realtime; security.events errors are durable, audit-relevant, and additionally use mail when explicit user targets exist. Hosts may persist category policies and per-channel preferences through the feature-owned store ports.

Channel Provider Discovery

Optional channel packages or future plugins register IEltheonNotificationChannelProvider implementations through DI. INotificationChannelProviderRegistry exposes their descriptors and resolves providers using case-insensitive channel keys. The package supplies inapp and optional realtime providers; the template supplies the current mail adapter and inbox/policy stores. Compatibility overloads use that same policy path once these services are available, so Service and lifecycle publishers honor administrative channel settings.

Events

NotificationBus can publish lifecycle events when an IEventBus is available in DI:

• Eltheon.Notifications.NotificationPublished
• Eltheon.Notifications.NotificationFailed
• Eltheon.Notifications.NotificationAuditRequested

AddEltheonNotifications() registers notification event metadata but does not register the concrete EventBus. The host must add the Events package if lifecycle event publication is desired.

Events are enabled by default and can be disabled:

builder.Services.Configure<NotificationEventOptions>(options =>
{
    options.EnableEvents = false;
});

The EventBus-to-notification bridge remains opt-in through NotificationEventOptions.EnableEventBridge.

Metrics

If an IMetrics implementation is registered, publish attempts are counted with:

• eltheon_notifications_publish_total{provider,scope,severity,outcome}
• eltheon_notifications_delivery_total{channel,outcome,operation}

If no metrics implementation exists, notification delivery continues without a metrics dependency.

The external metrics ports remain write-only contracts. Independently of an exporter, NotificationOperationalMetrics keeps the rolling in-process delivery counters used by the RCL cockpit. Hosts requiring delivery history across restarts must provide a queryable telemetry adapter or intentionally persisted diagnostic records.

Notes

• Register custom sinks by implementing INotificationSink.
• The Admin/User RCL clients use EltheonJS.api for API-first operations, pageManager for feature initialization, and realtime plus polling fallback for header updates.
• The host shell retains only the top-header load point; notification pages, APIs and client behavior remain feature-owned.
• Notification title and body are not copied into lifecycle events.
• Realtime delivery is a bridge, not a package dependency. Hosts choose the concrete transport.