lmxopcua/docs/v2/admin-ui.md

Admin Web UI — OtOpcUa v2

Status: DRAFT — companion to plan.md §4 and config-db-schema.md. Defines the Blazor Server admin app for managing the central config DB.

Branch: v2 Created: 2026-04-17

Scope

This document covers the OtOpcUa Admin web app — the operator-facing UI for managing fleet configuration. It owns every write to the central config DB; OtOpcUa nodes are read-only consumers.

Out of scope here:

• Per-node operator dashboards (status, alarm acks for runtime concerns) — that's the existing Status Dashboard, deployed alongside each node, not the Admin app
• Driver-specific config screens — these are deferred to each driver's implementation phase per decision #27, and each driver doc is responsible for sketching its config UI surface
• Authentication of the OPC UA endpoint itself — covered by Security.md (LDAP)

Tech Stack

Aligned with ScadaLink CentralUI (scadalink-design/src/ScadaLink.CentralUI) — operators using both apps see the same login screen, same sidebar, same component vocabulary. Same patterns, same aesthetic.

Component	Choice	Reason
Framework	Blazor Server (.NET 10 Razor Components, AddInteractiveServerComponents)	Same as ScadaLink; real-time UI without separate SPA build; SignalR built-in for live cluster status
Hosting	Co-deploy with central DB by default; standalone option	Most deployments run Admin on the same machine as MSSQL; large fleets can split
Auth	LDAP bind via LdapAuthService (sibling of ScadaLink.Security) + cookie auth + JwtTokenService for API tokens	Direct parity with ScadaLink — same login form, same cookie scheme, same claim shape, same RoleMapper pattern. Operators authenticated to one app feel at home in the other
DB access	EF Core (same Configuration project that nodes use)	Schema versioning lives in one place
Real-time	SignalR (Blazor Server's underlying transport)	Live updates on ClusterNodeGenerationState and crash-loop alerts
Styling	Bootstrap 5 vendored under wwwroot/lib/bootstrap/	Direct parity with ScadaLink; standard component vocabulary (card, table, alert, btn, form-control, modal); no third-party Blazor-component-library dependency
Shared components	DataTable, ConfirmDialog, LoadingSpinner, ToastNotification, TimestampDisplay, RedirectToLogin, NotAuthorizedView	Same set as ScadaLink CentralUI; copy structurally so cross-app feel is identical
Reconnect overlay	Custom Bootstrap modal triggered on Blazor SignalR disconnect	Same pattern as ScadaLink — modal appears on connection loss, dismisses on reconnect

Code organization

Mirror ScadaLink's layout exactly:

src/
  ZB.MOM.WW.OtOpcUa.Admin/                        # Razor Components project (.NET 10)
    Auth/
      AuthEndpoints.cs                            # /auth/login, /auth/logout, /auth/token
      CookieAuthenticationStateProvider.cs        # bridges cookie auth to Blazor <AuthorizeView>
    Components/
      Layout/
        MainLayout.razor                          # dark sidebar + light main flex layout
        NavMenu.razor                             # role-gated nav sections
      Pages/
        Login.razor                               # server-rendered HTML form POSTing to /auth/login
        Dashboard.razor                           # default landing
        Clusters/
        Generations/
        Credentials/
        Audit/
      Shared/
        DataTable.razor                           # paged/sortable/filterable table (verbatim from ScadaLink)
        ConfirmDialog.razor
        LoadingSpinner.razor
        ToastNotification.razor
        TimestampDisplay.razor
        RedirectToLogin.razor
        NotAuthorizedView.razor
    EndpointExtensions.cs                         # MapAuthEndpoints + role policies
    ServiceCollectionExtensions.cs                # AddCentralAdmin
  ZB.MOM.WW.OtOpcUa.Admin.Security/               # LDAP + role mapping + JWT (sibling of ScadaLink.Security)

The Admin.Security project carries LdapAuthService, RoleMapper, JwtTokenService, AuthorizationPolicies. If it ever makes sense to consolidate with ScadaLink's identical project, lift to a shared internal NuGet — out of scope for v2.0 to keep OtOpcUa decoupled from ScadaLink's release cycle.

Authentication & Authorization

Operator authentication

Identical pattern to ScadaLink CentralUI. Operators log in via LDAP bind against the GLAuth server. The login flow is a server-rendered HTML form POSTing to /auth/login (NOT a Blazor interactive form — data-enhance="false" to disable Blazor enhanced navigation), handled by a minimal-API endpoint that:

1. Reads username / password from form
2. Calls LdapAuthService.AuthenticateAsync(username, password) — performs LDAP bind, returns Username, DisplayName, Groups
3. Calls RoleMapper.MapGroupsToRolesAsync(groups) — translates LDAP groups → application roles + cluster-scope set
4. Builds ClaimsIdentity with Name, DisplayName, Username, Role (multiple), ClusterId scope claims (multiple, when not system-wide)
5. HttpContext.SignInAsync(CookieAuthenticationDefaults.AuthenticationScheme, principal, ...) with IsPersistent = true, ExpiresUtc = +30 min (sliding)
6. Redirects to /
7. On failure, redirects to /login?error={URL-encoded message}

A parallel /auth/token endpoint returns a JWT for API clients (CLI tooling, scripts) — same auth, different transport. Symmetric with ScadaLink's pattern.

CookieAuthenticationStateProvider bridges the cookie principal to Blazor's AuthenticationStateProvider so <AuthorizeView> and [Authorize] work in components.

LDAP group → role mapping

LDAP group	Admin role	Capabilities
OtOpcUaAdmins	FleetAdmin	Everything: cluster CRUD, node CRUD, credential management, publish/rollback any cluster
OtOpcUaConfigEditors	ConfigEditor	Edit drafts and publish for assigned clusters; cannot create/delete clusters or manage credentials
OtOpcUaViewers	ReadOnly	View-only access to all clusters and generations; cannot edit drafts or publish

AuthorizationPolicies constants (mirrors ScadaLink): RequireFleetAdmin, RequireConfigEditor, RequireReadOnly. <AuthorizeView Policy="@AuthorizationPolicies.RequireFleetAdmin"> gates nav menu sections and page-level access.

Cluster-scoped grants (lifted from v2.1 to v2.0)

Because ScadaLink already has the site-scoped grant pattern (PermittedSiteIds claim, IsSystemWideDeployment flag), we get cluster-scoped grants essentially for free in v2.0 by mirroring it:

• A ConfigEditor user mapped to LDAP group OtOpcUaConfigEditors-LINE3 is granted ConfigEditor role + ClusterId=LINE3-OPCUA scope claim only
• The RoleMapper reads a small LdapGroupRoleMapping table (Group → Role, Group → ClusterId scope) configured by FleetAdmin via the Admin UI
• All cluster-scoped pages check both role AND ClusterId scope claim before showing edit affordances

System-wide users (no ClusterId scope claims, IsSystemWideDeployment = true) see every cluster.

Bootstrap (first-run)

Same as ScadaLink: a local-admin login configured in appsettings.json (or a local certificate-authenticated user) bootstraps the first OtOpcUaAdmins LDAP group binding before LDAP-only access takes over. Documented as a one-time setup step.

Audit

Every write operation goes through sp_* procs that log to ConfigAuditLog with the operator's principal. The Admin UI also logs view-only actions (page navigation, generation diff views) to a separate UI access log for compliance.

Visual Design — Direct Parity with ScadaLink

Every visual element is lifted from ScadaLink CentralUI's design system to ensure cross-app consistency. Concrete specs:

Layout

• Flex layout: <div class="d-flex"> containing <NavMenu /> (sidebar) and <main class="flex-grow-1 p-3"> (content)
• Sidebar: 220px fixed width (min-width: 220px; max-width: 220px), full viewport height (min-height: 100vh), background #212529 (Bootstrap dark)
• Main background: #f8f9fa (Bootstrap light)
• Brand: "OtOpcUa" in white bold (font-size: 1.1rem, padding 1rem, border-bottom 1px solid #343a40) at top of sidebar
• Nav links: color #adb5bd, padding 0.4rem 1rem, font-size 0.9rem. Hover: white text, background #343a40. Active: white text, background #0d6efd (Bootstrap primary)
• Section headers ("Admin", "Configuration", "Monitoring"): color #6c757d, uppercase, font-size 0.75rem, font-weight 600, letter-spacing 0.05em, padding 0.75rem 1rem 0.25rem
• User strip at bottom of sidebar: display name (text-light small) + Sign Out button (btn-outline-light btn-sm), separated from nav by border-top border-secondary

Login page

Verbatim structure from ScadaLink's Login.razor:

<div class="container" style="max-width: 400px; margin-top: 10vh;">
    <div class="card shadow-sm">
        <div class="card-body p-4">
            <h4 class="card-title mb-4 text-center">OtOpcUa</h4>

            @if (!string.IsNullOrEmpty(ErrorMessage))
            {
                <div class="alert alert-danger py-2" role="alert">@ErrorMessage</div>
            }

            <form method="post" action="/auth/login" data-enhance="false">
                <div class="mb-3">
                    <label for="username" class="form-label">Username</label>
                    <input type="text" class="form-control" id="username" name="username"
                           required autocomplete="username" autofocus />
                </div>
                <div class="mb-3">
                    <label for="password" class="form-label">Password</label>
                    <input type="password" class="form-control" id="password" name="password"
                           required autocomplete="current-password" />
                </div>
                <button type="submit" class="btn btn-primary w-100">Sign In</button>
            </form>
        </div>
    </div>
    <p class="text-center text-muted mt-3 small">Authenticate with your organization's LDAP credentials.</p>
</div>

Exact same dimensions, exact same copy pattern, only the brand name differs.

Reconnection overlay

Same SignalR-disconnect modal as ScadaLink — #reconnect-modal overlay (rgba(0,0,0,0.5) backdrop, centered white card with spinner-border text-primary, "Connection Lost" heading, "Attempting to reconnect to the server. Please wait..." body). Listens for Blazor.addEventListener('enhancedload') to dismiss on reconnect. Lifted from ScadaLink's App.razor inline styles.

Shared components — direct copies

All seven shared components from ScadaLink CentralUI are copied verbatim into our Components/Shared/:

Component	Use
DataTable.razor	Sortable, filterable, paged table — used for tags, generations, audit log, cluster list
ConfirmDialog.razor	Modal confirmation for destructive actions (publish, rollback, discard draft, disable credential)
LoadingSpinner.razor	Standard spinner for in-flight DB operations
ToastNotification.razor	Transient success/error toasts for non-modal feedback
TimestampDisplay.razor	Consistent UTC + relative-time rendering ("3 minutes ago")
RedirectToLogin.razor	Component used by pages requiring auth — server-side redirect to /login?returnUrl=...
NotAuthorizedView.razor	Standard "you don't have permission for this action" view, shown by <AuthorizeView> Not authorized branch

If we discover an Admin-specific component need, add it to our Shared folder rather than diverging from ScadaLink's set.

Information Architecture

/                                Fleet Overview (default landing)
/clusters                        Cluster list
/clusters/{ClusterId}            Cluster detail (tabs: Overview / Namespaces / UNS Structure / Drivers / Devices / Equipment / Tags / Generations / Audit)
/clusters/{ClusterId}/nodes/{NodeId}             Node detail
/clusters/{ClusterId}/namespaces                 Namespace management (generation-versioned via draft → publish; same boundary as drivers/tags)
/clusters/{ClusterId}/uns                        UNS structure management (areas, lines, drag-drop reorganize)
/clusters/{ClusterId}/equipment                  Equipment list (default sorted by ZTag)
/clusters/{ClusterId}/equipment/{EquipmentId}    Equipment detail (5 identifiers, UNS placement, signals, audit)
/clusters/{ClusterId}/draft                      Draft editor (drivers/devices/equipment/tags)
/clusters/{ClusterId}/draft/diff                 Draft vs current diff viewer
/clusters/{ClusterId}/generations                Generation history
/clusters/{ClusterId}/generations/{Id}           Generation detail (read-only view of any generation)
/clusters/{ClusterId}/audit                      Audit log filtered to this cluster
/credentials                     Credential management (FleetAdmin only)
/audit                           Fleet-wide audit log
/admin/users                     Admin role assignments (FleetAdmin only)

Core Pages

Fleet Overview (/)

Single-page summary intended as the operator landing page.

• Cluster cards, one per ServerCluster, showing:
  • Cluster name, site, redundancy mode, node count
  • Per-node status: online/offline (from ClusterNodeGenerationState.LastSeenAt), current generation, RedundancyRole, ServiceLevel (last reported)
  • Drift indicator: red if 2-node cluster's nodes are on different generations, amber if mid-apply, green if converged
• Active alerts strip (top of page):
  • Sticky crash-loop circuit alerts (per driver-stability.md)
  • Stragglers: nodes that haven't applied the latest published generation within 5 min
  • Failed applies (LastAppliedStatus = 'Failed')
• Recent activity: last 20 events from ConfigAuditLog across the fleet
• Search bar at top: jump to any cluster, node, tag, or driver instance by name

Refresh: SignalR push for status changes; full reload every 30 s as a safety net.

Cluster Detail (/clusters/{ClusterId})

Tabbed view for one cluster.

Tabs:

1. Overview — cluster metadata (name, Enterprise, Site, redundancy mode), namespace summary (which kinds are configured + their URIs), node table with online/offline/role/generation/last-applied-status, current published generation summary, draft status (none / in progress / ready to publish)

2. Namespaces — list of Namespace rows for this cluster in the current published generation (Kind, NamespaceUri, Enabled). Namespaces are generation-versioned (revised after adversarial review finding #2): add / disable / re-enable a namespace by opening a draft, making the change, and publishing. The tab is read-only when no draft is open; "Edit in draft" button opens the cluster's draft scoped to the namespace section. Equipment kind is auto-included in the cluster's first generation; SystemPlatform kind is added when a Galaxy driver is configured. Simulated kind is reserved (operator can add a row of Kind = 'Simulated' in a draft but no driver populates it in v2.0; UI shows "Awaiting replay driver — see roadmap" placeholder).

3. UNS Structure — tree view of UnsArea → UnsLine → Equipment for this cluster's current published generation. Operators can:

   • Add/rename/delete areas and lines (changes go into the active draft)
   • Bulk-move lines between areas (drag-and-drop in the tree, single edit propagates UNS path changes to all equipment under the moved line)
   • Bulk-move equipment between lines
   • View live UNS path preview per node (Enterprise/Site/Area/Line/Equipment)
   • See validation errors inline (segment regex, length cap, _default placeholder rules)
   • Counts per node: # lines per area, # equipment per line, # signals per equipment
   • Path-rename impact: when renaming an area, UI shows "X lines, Y equipment, Z signals will pick up new path" before commit

4. Drivers — table of DriverInstance rows in the current published generation, with per-row namespace assignment shown. Per-row navigation to driver-specific config screens. "Edit in draft" button creates or opens the cluster's draft.

5. Devices — table of Device rows (where applicable), grouped by DriverInstance

6. Equipment — table of Equipment rows in the current published generation, scoped to drivers in Equipment-kind namespaces. Default sort: ZTag ascending (the primary browse identifier per decision #117). Default columns:

   • ZTag (primary, bold, copyable)
   • MachineCode (secondary, e.g. machine_001)
   • Full UNS path (rendered live from cluster + UnsLine→UnsArea + Equipment.Name)
   • SAPID (when set)
   • EquipmentUuid (collapsed badge, copyable on click — "show UUID" toggle to expand)
   • EquipmentClassRef (placeholder until schemas repo lands)
   • DriverInstance, DeviceId, Enabled

   Search bar supports any of the five identifiers (ZTag, MachineCode, SAPID, EquipmentId, EquipmentUuid) — operator types and the search dispatches across all five with a typeahead that disambiguates ("Found in ZTag" / "Found in MachineCode" labels on each suggestion). Per-row click opens the Equipment Detail page.

7. Tags — paged, filterable table of all tags. Filters: namespace kind, equipment (by ZTag/MachineCode/SAPID), driver, device, folder path, name pattern, data type. For Equipment-ns tags the path is shown as the full UNS path; for SystemPlatform-ns tags the v1-style FolderPath/Name is shown. Bulk operations toolbar: export to CSV, import from CSV (validated against active draft).

8. ACLs — OPC UA client data-path authorization grants. Two views (toggle at top): "By LDAP group" (rows) and "By scope" (UNS tree with permission badges per node). Bulk-grant flow: pick group + permission bundle (ReadOnly / Operator / Engineer / Admin) or per-flag selection + scope (multi-select from tree or pattern), preview, confirm via draft. Permission simulator panel: enter username + LDAP groups → effective permission map across the cluster's UNS tree. Default seed on cluster creation maps v1 LmxOpcUa LDAP roles. Banner shows when this cluster's ACL set diverges from the seed. See acl-design.md for full design.

9. Generations — generation history list (see Generation History page)

10. Audit — filtered audit log

The Drivers/Devices/Equipment/Tags tabs are read-only views of the published generation; editing is done in the dedicated draft editor to make the publish boundary explicit. The Namespaces tab and the UNS Structure tab follow the same hybrid pattern: navigation is read-only over the published generation, click-to-edit on any node opens the draft editor scoped to that node. No table in v2.0 is edited outside the publish boundary (revised after adversarial review finding #2).

Equipment Detail (/clusters/{ClusterId}/equipment/{EquipmentId})

Per-equipment view. Form sections:

• OPC 40010 Identification panel (per the _base equipment-class template): operator-set static metadata exposed as OPC UA properties on the equipment node's Identification sub-folder — Manufacturer (required), Model (required), SerialNumber, HardwareRevision, SoftwareRevision, YearOfConstruction, AssetLocation (free-text supplementary to UNS path), ManufacturerUri (URL), DeviceManualUri (URL). Manufacturer + Model are required because the _base template declares them as isRequired: true; the rest are optional and can be filled in over time. Drivers that can read fields dynamically (e.g. FANUC cnc_sysinfo() returning SoftwareRevision) override the static value at runtime; otherwise the operator-set value flows through.
• Identifiers panel: all five identifiers, with explicit purpose labels and copy-to-clipboard buttons
  • ZTag — editable; live fleet-wide uniqueness check via ExternalIdReservation (warns if value is currently held by another EquipmentUuid; cannot save unless reservation is released first)
  • MachineCode — editable; live within-cluster uniqueness check
  • SAPID — editable; same reservation-backed check as ZTag
  • EquipmentId — read-only forever (revised after adversarial review finding #4). System-generated as 'EQ-' + first 12 hex chars of EquipmentUuid. Never operator-editable, never present in any input form, never accepted from CSV imports
  • EquipmentUuid — read-only forever (auto-generated UUIDv4 on creation, never editable; copyable badge with "downstream consumers join on this" tooltip)
• UNS placement panel: UnsArea/UnsLine pickers (typeahead from existing structure); Equipment.Name field with live segment validation; live full-path preview with character counter
• Class template panel: EquipmentClassRef — free text in v2.0; becomes a typeahead picker when schemas repo lands
• Driver source panel: DriverInstance + DeviceId pickers (filtered to drivers in Equipment-kind namespaces of this cluster)
• Signals panel: list of Tag rows that belong to this equipment; inline edit not supported here (use Draft Editor's Tags panel for editing); read-only with a "Edit in draft" deep link
• Audit panel: filtered audit log scoped to this equipment row across generations

Node Detail (/clusters/{ClusterId}/nodes/{NodeId})

Per-node view for ClusterNode management.

• Physical attributes form: Host, OpcUaPort, DashboardPort, ApplicationUri, ServiceLevelBase, RedundancyRole
• ApplicationUri auto-suggest behavior (per decision #86):
  • When creating a new node: prefilled with urn:{Host}:OtOpcUa
  • When editing an existing node: changing Host shows a warning banner — "ApplicationUri is not updated automatically. Changing it will require all OPC UA clients to re-establish trust." Operator must explicitly click an "Update ApplicationUri" button to apply the suggestion.
• Credentials sub-tab: list of ClusterNodeCredential rows (kind, value, enabled, rotated-at). FleetAdmin can add/disable/rotate. Credential rotation flow is documented inline ("create new credential → wait for node to use it → disable old credential").
• Per-node overrides sub-tab: structured editor for DriverConfigOverridesJson. Surfaces the cluster's DriverInstance rows with their current DriverConfig, and lets the operator add path → value override entries per driver. Validation: override path must exist in the current draft's DriverConfig; loud failure if it doesn't (per the merge semantics in the schema doc).
• Generation state: current applied generation, last-applied timestamp, last-applied status, last error if any
• Recent node activity: filtered audit log

Draft Editor (/clusters/{ClusterId}/draft)

The primary edit surface. Three-panel layout: tree on the left (Drivers → Devices → Equipment → Tags, with Equipment shown only for drivers in Equipment-kind namespaces), edit form on the right, validation panel at the bottom.

• Drivers panel: add/edit/remove DriverInstance rows in the draft. Each driver type opens a driver-specific config screen (deferred per #27). Generic fields (Name, NamespaceId, Enabled) are always editable. The NamespaceId picker is filtered to namespace kinds that are valid for the chosen driver type (e.g. selecting DriverType=Galaxy restricts the picker to SystemPlatform-kind namespaces only).
• Devices panel: scoped to the selected driver instance (where applicable)
• UNS Structure panel (Equipment-ns drivers only): tree of UnsArea → UnsLine; CRUD on areas and lines; rename and move operations with live impact preview ("renaming bldg-3 → bldg-3a will update 12 lines, 47 equipment, 1,103 signal paths"); validator rejects identity reuse with a different parent
• Equipment panel (Equipment-ns drivers only):
  • Add/edit/remove Equipment rows scoped to the selected driver
  • Inline form sections:
    • Identifiers: MachineCode (required, e.g. machine_001, validates within-cluster uniqueness live); ZTag (optional, ERP id, validates fleet-wide uniqueness via ExternalIdReservation lookup live — surfaces "currently reserved by EquipmentUuid X in cluster Y" if collision); SAPID (optional, SAP PM id, same reservation-backed check)
    • UNS placement: UnsLineId picker (typeahead from existing structure or "Create new line" inline); Name (UNS level 5, live segment validation ^[a-z0-9-]{1,32}$)
    • Class template: EquipmentClassRef (free text in v2.0; becomes a typeahead picker when schemas repo lands)
    • Source: DeviceId (when driver has multiple devices); Enabled
  • EquipmentUuid is auto-generated UUIDv4 on creation, displayed read-only as a copyable badge, never editable. EquipmentId is also auto-generated ('EQ-' + first 12 hex chars of EquipmentUuid) and never editable in any form. Both stay constant across renames, MachineCode/ZTag/SAPID edits, and area/line moves. The validator rejects any draft that tries to change either value on a published equipment.
  • Live UNS path preview above the form: {Cluster.Enterprise}/{Cluster.Site}/{UnsArea.Name}/{UnsLine.Name}/{Name} with character count and ≤200 limit indicator
  • Bulk operations:
    • Move many equipment from one line to another (UUIDs and identifiers preserved)
    • Bulk-edit MachineCode/ZTag/SAPID via inline grid (validation per row)
    • Bulk-create equipment from CSV (one row per equipment; UUIDs auto-generated for new rows)
• Tags panel:
  • Tree view: by Equipment when in Equipment-ns; by FolderPath when in SystemPlatform-ns
  • Inline edit for individual tags (Name, DataType, AccessLevel, WriteIdempotent, PollGroupId, TagConfig JSON in a structured editor)
  • Bulk operations: select multiple tags → bulk edit (change poll group, access level, etc.)
  • CSV import schemas (one per namespace kind):
    • Equipment-ns: (EquipmentId, Name, DataType, AccessLevel, WriteIdempotent, PollGroupId, TagConfig)
    • SystemPlatform-ns: (DriverInstanceId, DeviceId?, FolderPath, Name, DataType, AccessLevel, WriteIdempotent, PollGroupId, TagConfig)
    • Preview shows additions/modifications/removals against current draft, with row-level validation errors. Operator confirms or cancels.
  • CSV export: emit the matching shape from the current published generation
  • Equipment CSV import (separate flow): bulk-create-or-update equipment. Columns: (EquipmentUuid?, MachineCode, ZTag?, SAPID?, UnsAreaName, UnsLineName, Name, DriverInstanceId, DeviceId?, EquipmentClassRef?). No EquipmentId column (revised after adversarial review finding #4 — operator-supplied EquipmentId would mint duplicate equipment identity on typos):
    • Row with EquipmentUuid set: matches existing equipment by UUID, updates the matched row's editable fields (MachineCode/ZTag/SAPID/UnsLineId/Name/EquipmentClassRef/DeviceId/Enabled). Mismatched UUID = error, abort row.
    • Row without EquipmentUuid: creates new equipment. System generates fresh UUID and EquipmentId = 'EQ-' + first 12 hex chars. Cannot be used to update an existing row — operator must include UUID for updates.
    • UnsArea/UnsLine resolved by name within the cluster (auto-create if not present, with validation prompt).
    • Identifier uniqueness checks run row-by-row with errors surfaced before commit. ZTag/SAPID checked against ExternalIdReservation — collisions surface inline with the conflicting EquipmentUuid named.
    • Explicit "merge equipment A into B" or "rebind ZTag from A to B" operations are not in the CSV import path — see the Merge / Rebind operator flow below.
• Validation panel runs sp_ValidateDraft continuously (debounced 500 ms) and surfaces FK errors, JSON schema errors, duplicate paths, missing references, UNS naming-rule violations, UUID-immutability violations, and driver-type-vs-namespace-kind mismatches. Publish button is disabled while errors exist.
• Diff link at top: opens the diff viewer comparing the draft against the current published generation

Diff Viewer (/clusters/{ClusterId}/draft/diff)

Three-column compare: previous published | draft | summary. Per-table sections (drivers, devices, tags, poll groups) with rows colored by change type:

• Green: added in draft
• Red: removed in draft
• Yellow: modified (with field-level diff on hover/expand)

Includes a publish dialog triggered from this view: required Notes field, optional "publish and apply now" vs. "publish and let nodes pick up on next poll" (the latter is the default; the former invokes a one-shot push notification, deferred per existing plan).

Generation History (/clusters/{ClusterId}/generations)

List of all generations for the cluster with: ID, status, published-by, published-at, notes, and a per-row "Roll back to this" action (FleetAdmin or ConfigEditor). Clicking a row opens the generation detail page (read-only view of all rows in that generation, with diff-against-current as a button).

Rollback flow:

1. Operator clicks "Roll back to this generation"
2. Modal: "This will create a new published generation cloned from generation N. Both nodes of this cluster will pick up the change on their next poll. Notes (required):"
3. Confirm → invokes sp_RollbackToGeneration → immediate UI feedback that a new generation was published

Credential Management (/credentials)

FleetAdmin-only. Lists all ClusterNodeCredential rows fleet-wide, filterable by cluster/node/kind/enabled.

Operations: add credential to node, disable credential, mark credential rotated. Rotation is the most common operation — the UI provides a guided flow ("create new → confirm node has used it once via LastAppliedAt advance → disable old").

Fleet Audit (/audit)

Searchable / filterable view of ConfigAuditLog across all clusters. Filters: cluster, node, principal, event type, date range. Export to CSV for compliance.

Real-Time Updates

Blazor Server runs over SignalR by default. The Admin app uses two SignalR hubs:

Hub	Purpose
FleetStatusHub	Push ClusterNodeGenerationState changes (LastSeenAt updates, applied-generation transitions, status changes) to any open Fleet Overview or Cluster Detail page
AlertHub	Push new sticky alerts (crash-loop circuit trips, failed applies) to all subscribed pages

Updates fan out from a backend IHostedService that polls ClusterNodeGenerationState every 5 s and diffs against last-known state. Pages subscribe selectively (Cluster Detail page subscribes to one cluster's updates; Fleet Overview subscribes to all). No polling from the browser.

UX Rules

• Sticky alerts that don't auto-clear — per the crash-loop circuit-breaker rule in driver-stability.md, alerts in the Active Alerts strip require explicit operator acknowledgment before clearing, regardless of whether the underlying state has recovered. "We crash-looped 3 times overnight" must remain visible the next morning.
• Publish boundary is explicit — there is no "edit in place" path. All changes go through draft → diff → publish. The diff viewer is required reading before the publish dialog enables.
• Loud failures over silent fallbacks — if validation fails, the publish button is disabled and the failures are listed; we never publish a generation with warnings hidden. If a node override path doesn't resolve in the draft, the override editor flags it red, not yellow.
• No auto-rewrite of ApplicationUri — see Node Detail page above. The principle generalizes: any field that OPC UA clients pin trust to (ApplicationUri, certificate thumbprints) requires explicit operator action to change, never silent updates.
• Bulk operations always preview before commit — CSV imports, bulk tag edits, rollbacks all show a diff and require confirmation. No "apply" buttons that act without preview.

Per-Driver Config Screens (deferred)

Per decision #27, driver-specific config screens are added in each driver's implementation phase, not up front. The Admin app provides:

• A pluggable IDriverConfigEditor interface in Configuration.Abstractions
• Driver projects implement an editor that renders into a slot on the Driver Detail screen
• For drivers that don't yet have a custom editor, a generic JSON editor with schema-driven validation is used (better than nothing, ugly but functional)

The generic JSON editor uses the per-driver JSON schema from DriverTypeRegistry so even pre-custom-editor, validation works.

Workflows

Add a new cluster

1. FleetAdmin: /clusters → "New cluster"
2. Form: Name, Enterprise (UNS level 1, e.g. ent, validated ^[a-z0-9-]{1,32}$), Site (UNS level 2, e.g. warsaw-west, same validation), NodeCount (1 or 2), RedundancyMode (auto-set based on NodeCount)
3. Save → cluster row created (Enabled = 1, no generations yet)
4. Open initial draft containing default namespaces:
   • Equipment-kind namespace (NamespaceId = {ClusterName}-equipment, NamespaceUri = urn:{Enterprise}:{Site}:equipment). Operator can edit URI in the draft before publish.
   • Prompt: "This cluster will host a Galaxy / System Platform driver?" → if yes, the draft also includes a SystemPlatform-kind namespace (urn:{Enterprise}:{Site}:system-platform). If no, skip — operator can add it later via a draft.
5. Operator reviews the initial draft, optionally adds the first nodes' worth of drivers/equipment, then publishes generation 1. The cluster cannot serve any consumer until generation 1 is published (no namespaces exist before that).
6. Redirect to Cluster Detail; prompt to add nodes via the Node tab (cluster topology) — node addition itself remains cluster-level since ClusterNode rows are physical-machine topology, not consumer-visible content.

(Revised after adversarial review finding #2 — namespaces must travel through the publish boundary; the cluster-create flow no longer writes namespace rows directly.)

Add a node to a cluster

1. Cluster Detail → "Add node"
2. Form: NodeId, RedundancyRole, Host (required), OpcUaPort (default 4840), DashboardPort (default 8081), ApplicationUri (auto-prefilled urn:{Host}:OtOpcUa), ServiceLevelBase (auto: Primary=200, Secondary=150)
3. Save
4. Prompt: "Add a credential for this node now?" → opens credential add flow
5. The node won't be functional until at least one credential is added and the credential is provisioned on the node's machine (out-of-band step documented in deployment guide)

Edit drivers/tags and publish

1. Cluster Detail → "Edit configuration" → opens draft editor (creates a draft generation if none exists)
2. Operator edits drivers, devices, tags, poll groups
3. Validation panel updates live; publish disabled while errors exist
4. Operator clicks "Diff" → diff viewer
5. Operator clicks "Publish" → modal asks for Notes, confirms
6. sp_PublishGeneration runs in transaction; on success, draft becomes new published generation; previous published becomes superseded
7. Within ~30 s (default poll interval), both nodes pick up the new generation; Cluster Detail page shows live progress as LastAppliedAt advances on each node

Roll back

1. Cluster Detail → Generations tab → find target generation → "Roll back to this"
2. Modal: explains a new generation will be created (clone of target) and published; require Notes
3. Confirm → sp_RollbackToGeneration runs
4. Same propagation as a forward publish — both nodes pick up the new generation on next poll

Override a setting per node

1. Node Detail → Overrides sub-tab
2. Pick driver instance from dropdown → schema-driven editor shows current DriverConfig keys
3. Add override row: select key path (validated against the driver's JSON schema), enter override value
4. Save → updates ClusterNode.DriverConfigOverridesJson
5. No new generation created — overrides are per-node metadata, not generation-versioned. They take effect on the node's next config-apply cycle.

The "no new generation" choice is deliberate: overrides are operationally bound to a specific physical machine, not to the cluster's logical config evolution. A node replacement scenario would copy the override to the replacement node via the credential/override migration flow, not by replaying generation history.

Rotate a credential

1. Node Detail → Credentials sub-tab → "Add credential"
2. Pick Kind, enter Value, save → new credential is enabled alongside the old
3. Wait for LastAppliedAt on the node to advance (proves the new credential is being used by the node — operator-side work to provision the new credential on the node's machine happens out-of-band)
4. Once verified, disable the old credential → only the new one is valid

Release an external-ID reservation

When equipment is permanently retired and its ZTag or SAPID needs to be reusable by a different physical asset (a known-rare event):

1. FleetAdmin: navigate to Equipment Detail of the retired equipment, or to a global "External ID Reservations" view
2. Select the reservation (Kind + Value), click "Release"
3. Modal requires: confirmation of the EquipmentUuid that currently holds the reservation, and a free-text release reason (compliance audit trail)
4. Confirm → sp_ReleaseExternalIdReservation runs: sets ReleasedAt, ReleasedBy, ReleaseReason. Audit-logged with EventType = 'ExternalIdReleased'.
5. The same (Kind, Value) can now be reserved by a different EquipmentUuid in a future publish. The released row stays in the table forever for audit.

This is the only path that allows ZTag/SAPID reuse — no implicit release on equipment disable, no implicit release on cluster delete. Requires explicit FleetAdmin action with a documented reason.

Merge or rebind equipment (rare)

When operators discover that two EquipmentRows in different generations actually represent the same physical asset (e.g. a typo created a duplicate) — or when an asset's identity has been incorrectly split across UUIDs — the resolution is not an in-place EquipmentId edit (which is now impossible per finding #4). Instead:

1. FleetAdmin: Equipment Detail of the row that should be retained → "Merge from another EquipmentUuid"
2. Pick the source EquipmentUuid (the one to retire); modal shows a side-by-side diff of identifiers and signal counts
3. Confirm → opens a draft that:
   • Disables the source equipment row (Enabled = 0) and adds an EventType = 'EquipmentMergedAway' audit entry naming the target UUID
   • Re-points any tags currently on the source equipment to the target equipment
   • If the source held a ZTag/SAPID reservation that should move to the target: explicit release of the source's reservation followed by re-reservation under the target UUID, both audit-logged
4. Operator reviews the draft diff; publishes
5. Downstream consumers see the source EquipmentUuid disappear (joins on it return historical data only) and the target EquipmentUuid gain the merged tags

Merge is a destructive lineage operation — the source EquipmentUuid is never reused, but its history persists in old generations + audit log. Rare by intent; UI buries the action behind two confirmation prompts.

Deferred / Out of Scope

• Cluster-scoped admin grants (ConfigEditor for Cluster X only, not for Cluster Y) — surface in v2.1
• Per-driver custom config editors — added in each driver's implementation phase
• Tag template / inheritance — define a tag pattern once and apply to many similar device instances; deferred until the bulk import path proves insufficient
• Multi-cluster synchronized publish — push a configuration change across many clusters atomically. Out of scope; orchestrate via per-cluster publishes from a script if needed.
• Mobile / tablet layout — desktop-only initially
• Role grants editor in UI — initial v2 manages LDAP group → admin role mappings via appsettings.json; UI editor surfaced later

Decisions / Open Questions

Decided (captured in plan.md decision log):

• Blazor Server tech stack (vs. SPA + API)
• Visual + auth parity with ScadaLink CentralUI — Bootstrap 5, dark sidebar, server-rendered login form, cookie auth + JWT API endpoint, copied shared component set, reconnect overlay
• LDAP for operator auth via LdapAuthService + RoleMapper + JwtTokenService mirrored from ScadaLink.Security
• Three admin roles: FleetAdmin / ConfigEditor / ReadOnly, with cluster-scoped grants in v2.0 (mirrored from ScadaLink's site-scoped pattern)
• Draft → diff → publish is the only edit path; no in-place edits
• Sticky alerts require manual ack
• Per-node overrides are NOT generation-versioned
• All content edits go through the draft → diff → publish boundary — Namespaces, UNS Structure, Drivers, Devices, Equipment, Tags. The UNS Structure and Namespaces tabs are hybrid (read-only navigation over the published generation, click-to-edit opens the draft editor scoped to that node). No table is editable outside the publish boundary in v2.0 (revised after adversarial review finding #2 — earlier draft mistakenly treated namespaces as cluster-level)
• Equipment list defaults to ZTag sort (primary browse identifier per the 3-year-plan handoff). All five identifiers (ZTag/MachineCode/SAPID/EquipmentId/EquipmentUuid) are searchable; typeahead disambiguates which field matched
• EquipmentUuid is read-only forever in the UI; never editable. Auto-generated UUIDv4 on equipment creation, displayed as a copyable badge

Resolved Defaults:

• Styling: Bootstrap 5 vendored (not MudBlazor or Fluent UI). Direct parity with ScadaLink CentralUI; standard component vocabulary; no Blazor-specific component-library dependency. Reverses an earlier draft choice — the cross-app consistency requirement outweighs MudBlazor's component conveniences.
• Theme: light only (single theme matching ScadaLink). ScadaLink ships light-only with the dark sidebar / light main pattern. Operators using both apps see one consistent aesthetic. Reverses an earlier draft choice that proposed both light and dark — cross-app consistency wins. Revisit only if ScadaLink adds dark mode.
• CSV import dialect: strict CSV (RFC 4180), UTF-8 BOM accepted. Excel "Save as CSV (UTF-8)" produces RFC 4180-compatible output and is the documented primary input format. TSV not supported initially; add only if operator feedback shows real friction with Excel CSV.
• Push notification deferred to v2.1; polling is initial model. SignalR-from-DB-to-nodes would tighten apply latency from ~30 s to ~1 s but adds infrastructure (SignalR backplane or SQL Service Broker) that's not earning its keep at v2.0 scale. The publish dialog reserves a disabled "Push now" button labeled "Available in v2.1" so the future UX is anchored.
• Auto-save drafts with explicit Discard button. Every form field change writes to the draft rows immediately (debounced 500 ms). The Discard button shows a confirmation dialog ("Discard all changes since last publish?") and rolls the draft generation back to empty. The Publish button is the only commit; auto-save does not publish.
• Cluster-scoped admin grants in v2.0 (lifted from v2.1 deferred list). ScadaLink already ships the equivalent site-scoped pattern, so we get cluster-scoped grants essentially for free by mirroring it. RoleMapper reads an LdapGroupRoleMapping table; cluster-scoped users carry ClusterId claims and see only their permitted clusters.