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)

• 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.
• Manage recipients (name + email) within each 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, data connection definitions, notification lists, and SMTP configuration to all sites or to an individual site.
• 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, notifications, cached DB writes).
• View message details (target, payload, retry count, timestamps).
• Retry or discard individual parked messages.

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.

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.