scadalink-design/docs/requirements/Component-CentralUI.md

Component: Central UI

Purpose

The Central UI is a web-based management interface hosted on the central cluster. It provides all configuration, deployment, monitoring, and troubleshooting workflows for the SCADA system. There is no live machine data visualization — the UI is focused on system management, with the exception of on-demand debug views.

Location

Central cluster only. Sites have no user interface.

Technology

• Framework: Blazor Server (ASP.NET Core). UI logic executes on the server, updates pushed to the browser via SignalR.
• Keeps the entire stack in C#/.NET, consistent with the rest of the system (Akka.NET, EF Core).
• SignalR provides built-in support for real-time UI updates.

Failover Behavior

• A load balancer sits in front of the central cluster and routes to the active node.
• On central failover, the Blazor Server SignalR circuit is interrupted. The browser automatically attempts to reconnect via SignalR's built-in reconnection logic.
• Since sessions use authentication cookies carrying an embedded JWT (not server-side state), the user's authentication survives failover — the new active node validates the same cookie-embedded JWT. No re-login required if the token is still valid.
• Active debug view streams and in-progress deployment status subscriptions are lost on failover and must be re-opened by the user.
• Both central nodes share the same ASP.NET Data Protection keys (stored in the configuration database or shared configuration) so that tokens and anti-forgery tokens remain valid across failover.

Real-Time Updates

• Debug view: Real-time display of attribute values and alarm states via gRPC streaming. When the user opens a debug view, a DebugStreamBridgeActor on the central side opens a gRPC server-streaming subscription to the site's SiteStreamGrpcServer for the selected instance, then requests an initial DebugViewSnapshot via ClusterClient. Ongoing AttributeValueChanged and AlarmStateChanged events flow via the gRPC stream (not through ClusterClient) to the bridge actor, which delivers them to the Blazor component via callbacks that call InvokeAsync(StateHasChanged) to push UI updates through the built-in SignalR circuit.
• Health dashboard: Site status, connection health, error rates, and buffer depths update via a 10-second auto-refresh timer. Since health reports arrive from sites every 30 seconds, a 10s poll interval catches updates within one reporting cycle without unnecessary overhead.
• Deployment status: Pending/in-progress/success/failed transitions push to the UI immediately via SignalR (built into Blazor Server). No polling required for deployment tracking.

Responsibilities

• Provide authenticated access to all management workflows.
• Enforce role-based access control in the UI (Admin, Design, Deployment with site scoping).
• Present data from the configuration database, and from site clusters via remote queries.

Workflows / Pages

Template Authoring (Design Role)

• The /design/templates page uses a split-pane layout: a folder/template tree sidebar on the left and the editor on the right.
• The tree shows nested TemplateFolder entities with their templates underneath; composition children render inline as leaf nodes beneath their owning template (right-click "Open composed template" reveals and selects the target).
• Per-kind context menus on folder, template, and composition nodes expose the relevant operations (new folder, new template, rename, move, delete, move to folder). Native HTML5 drag-drop reorganizes templates between folders and reparents folders, with cycle detection rejected via toast on drop. Tree expansion state persists in sessionStorage, and deep links (/design/templates/{id}) reveal and select the target node.
• Create, edit, and delete templates.
• Template deletion is blocked if any instances or child templates reference the template. The UI displays the references preventing deletion.
• Manage template hierarchy (inheritance) — visual tree of parent/child relationships.
• Manage composition — add/remove feature module instances within templates. Naming collision detection provides immediate feedback if composed modules introduce duplicate attribute, alarm, or script names.
• Define and edit attributes, alarms, and scripts on templates.
• Set lock flags on attributes, alarms, and scripts.
• Visual indicator showing inherited vs. locally defined vs. overridden members.
• On-demand validation: A "Validate" action allows Design users to run comprehensive pre-deployment validation (flattening, naming collisions, script compilation, trigger references) without triggering a deployment. Provides early feedback during authoring.
• Last-write-wins editing — no pessimistic locks or conflict detection on templates.

Shared Script Management (Design Role)

• Create, edit, and delete shared (global) scripts.
• Shared scripts are not associated with any template.
• On-demand validation (compilation check) available.

External System Management (Design Role)

• Define external system contracts: connection details, API method definitions (parameters, return types).
• Define retry settings per external system (max retry count, fixed time between retries).

Database Connection Management (Design Role)

• Define named database connections: server, database, credentials.
• Define retry settings per connection (max retry count, fixed time between retries).

Notification List Management (Design Role)

• Create, edit, and delete notification lists.
• Each notification list has a Type — Email now, with Teams and other types planned. The type determines the type-specific targets a list carries.
• Manage recipients (name + email) within each Email list.
• Configure SMTP settings.

Site & Data Connection Management (Admin Role)

• Create, edit, and delete site definitions, including Akka node addresses (NodeA/NodeB) and gRPC node addresses (GrpcNodeA/GrpcNodeB).
• Define data connections and assign them to sites (name, protocol type, connection details).
• Data connection form: "Primary Endpoint Configuration" (required JSON text area) and optional "Backup Endpoint Configuration" (collapsible section, hidden by default, revealed via "Add Backup Endpoint" button; "Remove Backup" button when editing an existing backup). "Failover Retry Count" numeric input (default 3, min 1, max 20) is visible only when a backup endpoint is configured.
• Data connection list page: Shows Primary Config and Backup Config columns. Active Endpoint column populated from health reports.

Area Management (Admin Role)

• Define hierarchical area structures per site.
• Parent-child area relationships.
• Assign areas when managing instances.

Instance Management (Deployment Role)

• Create instances from templates at a specific site.
• Assign instances to areas.
• Bind data connections — per-attribute binding where each attribute with a data source reference individually selects its data connection from the site's available connections. Bulk assignment supported: select multiple attributes and assign a data connection to all of them at once.
• Set instance-level attribute overrides (non-locked attributes only).
• Filter/search instances by site, area, template, or status.
• Disable instances — stops data collection, script triggers, and alarm evaluation at the site while retaining the deployed configuration.
• Enable instances — re-activates a disabled instance.
• Delete instances — removes the running configuration from the site. Blocked if the site is unreachable. Store-and-forward messages are not cleared.

Deployment (Deployment Role)

• View list of instances with staleness indicators (deployed config differs from template-derived config).
• Filter by site, area, template.
• View diff between deployed and current template-derived configuration.
• Deploy updated configuration to individual instances. Pre-deployment validation runs automatically before any deployment is sent — validation errors are displayed and block deployment.
• Track deployment status (pending, in-progress, success, failed).

System-Wide Artifact Deployment (Deployment Role)

• Explicitly deploy shared scripts, external system definitions, database connection definitions, and data connection definitions to all sites or to an individual site. (Notification lists and SMTP configuration are central-only and are not deployed.)
• Per-site deployment: A "Deploy Artifacts" button on the Sites admin page allows deploying all artifacts to an individual site.
• Deploy all: A bulk action deploys artifacts to all sites at once.
• This is a separate action from instance deployment — system-wide artifacts are not automatically pushed when definitions change.
• Track per-site deployment status.

Debug View (Deployment Role)

• Select a deployed instance and open a live debug view.
• Real-time streaming of all attribute values (with quality and timestamp) and alarm states for that instance.
• The DebugStreamService creates a DebugStreamBridgeActor on the central side. The bridge actor opens a gRPC server-streaming subscription to the site's SiteStreamGrpcServer for the selected instance, then requests an initial DebugViewSnapshot via ClusterClient.
• Ongoing events (AttributeValueChanged, AlarmStateChanged) flow via the gRPC stream directly to the bridge actor — they do not pass through ClusterClient.
• Events are delivered to the Blazor component via callbacks, which call InvokeAsync(StateHasChanged) to push UI updates through the built-in SignalR circuit.
• A pulsing "Live" indicator replaces the static "Connected" badge when streaming is active.
• Stream includes attribute values formatted as [InstanceUniqueName].[AttributePath].[AttributeName] and alarm states formatted as [InstanceUniqueName].[AlarmName].
• Subscribe-on-demand — stream starts when opened, stops when closed.

Parked Message Management (Deployment Role)

• Query sites for parked messages (external system calls, cached DB writes). (Parked notifications are managed centrally on the Notification Outbox page, not here.)
• View message details (target, payload, retry count, timestamps).
• Retry or discard individual parked messages.

Notification Outbox (Deployment Role)

• Monitor and manage centrally-delivered notifications. The Notification Outbox dispatches every notification store-and-forwarded from sites and logs each one to the central Notifications table.
• KPI tiles at the top of the page: queue depth (Pending + Retrying), stuck count, parked count, delivered in the last interval, and oldest pending age. The KPIs are central-computed on demand from the Notifications table.
• A queryable notification list filterable by status, type, source site, notification list, and time range, with a stuck-only toggle and keyword search on subject. Each row shows the notification's status, retry count, last error, and key timestamps.
• Retry and Discard actions are available on parked notifications: Retry returns the notification to Pending and resets RetryCount / NextAttemptAt; Discard moves it to Discarded. The row is retained either way so the table stays a complete audit record.
• Stuck rows are visually badged — a notification is stuck if it is Pending or Retrying and older than the configurable stuck-age threshold. Stuck detection is display-only; there is no automated escalation or alerting.
• All queries are served from the central Notifications table — no remote per-site queries are needed, unlike the Parked Message Management page.

Health Monitoring Dashboard (All Roles)

• Overview of all sites with online/offline status.
• Per-site detail: active/standby node status, data connection health, script error rates, alarm evaluation error rates, store-and-forward buffer depths.
• Headline Notification Outbox KPI tiles — queue depth, stuck count, and parked count. These are central-computed by the Notification Outbox from the central Notifications table (not part of any site health report). The full outbox view is on the dedicated Notification Outbox page.

Site Event Log Viewer (Deployment Role)

• Query site event logs remotely.
• Filter by event type, time range, instance.
• View script executions, alarm events (activations, clears, evaluation errors), deployment events (including script compilation results), connection status changes, store-and-forward activity, instance lifecycle events (enable, disable, delete).

Audit Log Viewer (Admin Role)

• Query the central audit log.
• Filter by user, entity type, action type, time range.
• View before/after state for each change.

LDAP Group Mapping (Admin Role)

• Map LDAP groups to system roles (Admin, Design, Deployment).
• Configure site-scoping for Deployment role groups.

Dependencies

• Template Engine: Provides template and instance data models, flattening, diff calculation, and validation.
• Deployment Manager: Triggers deployments, system-wide artifact deployments, and instance lifecycle commands. Provides deployment status.
• Communication Layer: Routes debug view subscriptions, remote queries to sites.
• Security & Auth: Authenticates users and enforces role-based access.
• Configuration Database: All central data, including audit log data for the audit log viewer. Accessed via ICentralUiRepository.
• Health Monitoring: Provides site health data for the dashboard.
• Notification Outbox: Provides notification delivery KPIs and serves the Notifications table queries and Retry/Discard actions for the Notification Outbox page.