scadalink-design/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.

## 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.