Files

Joseph Doherty 34694adba2 Apply Codex review findings across all 17 components

Template Engine: add composed member addressing (path-qualified canonical names),
override granularity per entity type, semantic validation (call targets, arg types),
graph acyclicity enforcement, revision hashes for flattened configs.

Deployment Manager: add deployment ID + idempotency, per-instance operation lock
covering all mutating commands, state transition matrix, site-side apply atomicity
(all-or-nothing), artifact version compatibility policy.

Site Runtime: add script trust model (forbidden APIs, execution timeout, constrained
compilation), concurrency/serialization rules (Instance Actor serializes mutations),
site-wide stream backpressure (per-subscriber buffering, fire-and-forget publish).

Communication: add application-level correlation IDs for protocol safety beyond
Akka.NET transport guarantees.

External System Gateway: add 408/429 as transient errors, CachedCall idempotency
note, dedicated dispatcher for blocking I/O isolation.

Health Monitoring: add monotonic sequence numbers to prevent stale report overwrites.

Security: require LDAPS/StartTLS for LDAP connections.

Central UI: add failover behavior (SignalR reconnect, JWT survives, shared Data
Protection keys, load balancer readiness).

Cluster Infrastructure: add down-if-alone=on for safe singleton ownership.

Site Event Logging: clarify active-node-only logging (no replication), add 1GB
storage cap with oldest-first purge.

Host: add readiness gating (health check endpoint, no traffic until operational).

Commons: add message contract versioning policy (additive-only evolution).

Configuration Database: add optimistic concurrency on deployment status records.

2026-03-16 09:06:12 -04:00

8.5 KiB

Raw Blame History

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 JWT tokens (not server-side state), the user's authentication survives failover — the new active node validates the same JWT. No re-login required if the token is still valid.
Active debug view streams and in-progress real-time 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

All real-time features use server push via SignalR (built into Blazor Server):

Debug view: Attribute value and alarm state changes streamed live from sites.
Health dashboard: Site status, connection health, error rates, and buffer depths update automatically when new health reports arrive.
Deployment status: Pending/in-progress/success/failed transitions push to the UI immediately.

No manual refresh or polling is required for any of these features.

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.
Define data connections and assign them to sites (name, protocol type, connection details).

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 notification lists to all sites.
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.
Initial snapshot of current state followed by streaming updates via the site-wide Akka stream.
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.

8.5 KiB Raw Blame History