scadalink-design/Component-ManagementService.md

Component: Management Service

Purpose

The Management Service is an Akka.NET actor on the central cluster that provides programmatic access to all administrative operations. It exposes the same capabilities as the Central UI but through an actor-based interface, enabling the CLI (and potentially other tooling) to interact with the system without going through the web UI. The ManagementActor registers with ClusterClientReceptionist so that external processes can reach it via ClusterClient without joining the cluster.

Location

Central cluster only. The ManagementActor runs as a plain actor on every central node (not a cluster singleton). Because the actor is completely stateless — it holds no locks and no local state, delegating all work to repositories and services — running on all nodes improves availability without requiring coordination between instances. Either node can serve any request independently.

src/ScadaLink.ManagementService/

Responsibilities

• Provide an actor-based interface to all administrative operations available in the Central UI.
• Register with Akka.NET ClusterClientReceptionist so external tools (CLI) can discover and communicate with it via ClusterClient.
• Validate and authorize all incoming commands using the authenticated user identity carried in message envelopes.
• Delegate to the appropriate services and repositories for each operation.
• Return structured response messages for all commands and queries.
• Failover: The ManagementActor runs on all central nodes, so no actor-level failover is needed. If one node goes down, the ClusterClient transparently routes to the ManagementActor on the remaining node.

Key Classes

ManagementActor

The central actor that receives and processes all management commands. Registered at a well-known actor path (/user/management) and with ClusterClientReceptionist.

Message Contracts

All request/response messages are defined in Commons under Messages/Management/. Messages follow the existing additive-only evolution rules for version compatibility. Every request message includes:

• CorrelationId: Application-level correlation ID for request/response pairing.
• AuthenticatedUser: The identity and roles of the user issuing the command (username, display name, roles, permitted sites). This is populated by the CLI from the user's authenticated session.

ClusterClientReceptionist Registration

The ManagementActor registers itself with ClusterClientReceptionist at startup. This allows external processes using ClusterClient to send messages to the ManagementActor without joining the Akka.NET cluster as a full member. The receptionist advertises the actor under its well-known path.

Message Groups

Templates

• ListTemplates / GetTemplate: Query template definitions.
• CreateTemplate / UpdateTemplate / DeleteTemplate: Manage templates.
• ValidateTemplate: Run on-demand pre-deployment validation (flattening, naming collisions, script compilation).
• GetTemplateDiff: Compare deployed vs. template-derived configuration for an instance.

Template Members

• AddTemplateAttribute / UpdateTemplateAttribute / DeleteTemplateAttribute: Manage attributes on a template.
• AddTemplateAlarm / UpdateTemplateAlarm / DeleteTemplateAlarm: Manage alarm definitions on a template.
• AddTemplateScript / UpdateTemplateScript / DeleteTemplateScript: Manage scripts on a template.
• AddTemplateComposition / DeleteTemplateComposition: Manage feature module compositions on a template.

Instances

• ListInstances / GetInstance: Query instances, with filtering by site and area.
• CreateInstance: Create a new instance from a template.
• UpdateInstanceOverrides: Set attribute overrides on an instance.
• SetInstanceBindings / BindDataConnections: Bind data connections to instance attributes.
• AssignArea: Assign an instance to an area.
• EnableInstance / DisableInstance / DeleteInstance: Instance lifecycle commands.

Sites

• ListSites / GetSite: Query site definitions.
• CreateSite / UpdateSite / DeleteSite: Manage site definitions.
• ListAreas / CreateArea / UpdateArea / DeleteArea: Manage area hierarchies per site.

Data Connections

• ListDataConnections / GetDataConnection: Query data connection definitions.
• CreateDataConnection / UpdateDataConnection / DeleteDataConnection: Manage data connection definitions.
• AssignDataConnectionToSite / UnassignDataConnectionFromSite: Manage site assignments.

Deployments

• DeployInstance: Deploy configuration to a specific instance (includes pre-deployment validation).
• DeployArtifacts: Deploy system-wide artifacts (shared scripts, external system definitions, DB connections, data connections, notification lists, SMTP config) to all sites or a specific site.
• GetDeploymentStatus: Query deployment status.

External Systems

• ListExternalSystems / GetExternalSystem: Query external system definitions.
• CreateExternalSystem / UpdateExternalSystem / DeleteExternalSystem: Manage external system definitions.

Notifications

• ListNotificationLists / GetNotificationList: Query notification lists.
• CreateNotificationList / UpdateNotificationList / DeleteNotificationList: Manage notification lists and recipients.
• GetSmtpConfig / UpdateSmtpConfig: Query and update SMTP configuration.

Security (LDAP & API Keys)

• ListApiKeys / CreateApiKey / UpdateApiKey / EnableApiKey / DisableApiKey / DeleteApiKey: Manage API keys.
• ListRoleMappings / CreateRoleMapping / UpdateRoleMapping / DeleteRoleMapping: Manage LDAP group-to-role mappings.
• ListScopeRules / AddScopeRule / DeleteScopeRule: Manage site scope rules on role mappings.

Audit Log

• QueryAuditLog: Query audit log entries with filtering by entity type, user, date range, etc.

Shared Scripts

• ListSharedScripts / GetSharedScript: Query shared script definitions.
• CreateSharedScript / UpdateSharedScript / DeleteSharedScript: Manage shared scripts.

Database Connections

• ListDatabaseConnections / GetDatabaseConnection: Query database connection definitions.
• CreateDatabaseConnection / UpdateDatabaseConnection / DeleteDatabaseConnection: Manage database connections.

Inbound API Methods

• ListApiMethods / GetApiMethod: Query inbound API method definitions.
• CreateApiMethod / UpdateApiMethod / DeleteApiMethod: Manage inbound API methods.

Health

• GetHealthSummary: Query current health status of all sites.
• GetSiteHealth: Query detailed health for a specific site.

Remote Queries

• QuerySiteEventLog: Query site event log entries from a remote site (routed via communication layer). Supports date range, keyword search, and pagination.
• QueryParkedMessages: Query parked (dead-letter) messages at a remote site (routed via communication layer). Supports pagination.
• DebugSnapshot: Request a one-shot snapshot of attribute values and alarm states for a running instance. Resolves the instance's site from the config DB and routes via the communication layer. Uses 30s QueryTimeout.

Authorization

Every incoming message carries the authenticated user's identity and roles. The ManagementActor enforces the same role-based authorization rules as the Central UI:

• Admin role required for: site management, area management, API key management, role mapping management, scope rule management, system configuration.
• Design role required for: template authoring (including template member management: attributes, alarms, scripts, compositions), shared scripts, external system definitions, database connection definitions, notification lists, inbound API method definitions.
• Deployment role required for: instance management, deployments, debug view, debug snapshot, parked message queries, site event log queries. Site scoping is enforced for site-scoped Deployment users.
• Read-only access (any authenticated role): health summary, health site, site event log queries, parked message queries.

Unauthorized commands receive an Unauthorized response message. Failed authorization attempts are not audit logged (consistent with existing behavior).

Service Dependencies (DI)

The ManagementActor receives the following services and repositories via DI (injected through the actor's constructor or via a service provider):

• ITemplateEngineRepository / TemplateService — Template operations.
• InstanceService — Instance lifecycle and configuration.
• ISiteRepository — Site definitions and area management.
• IDeploymentManagerRepository / DeploymentService — Deployment pipeline operations.
• ArtifactDeploymentService — System-wide artifact deployment.
• IExternalSystemRepository — External system definitions.
• INotificationRepository — Notification lists and SMTP config.
• ISecurityRepository — API keys and LDAP role mappings.
• IInboundApiRepository — Inbound API method definitions.
• ISharedScriptRepository / SharedScriptService — Shared script definitions.
• IDatabaseConnectionRepository — Database connection definitions.
• ICentralHealthAggregator — Health status aggregation.
• CommunicationService — Central-site communication for deployment and remote queries.

Configuration

Section	Options Class	Contents
ScadaLink:ManagementService	ManagementServiceOptions	(Reserved for future configuration — e.g., command timeout overrides)

Dependencies

• Commons: Message contracts (Messages/Management/), shared types, repository interfaces.
• Configuration Database (MS SQL): All queries and mutations go through repositories backed by EF Core.
• Configuration Database (via IAuditService): All mutating operations are audit logged through the existing transactional audit mechanism.
• Communication Layer: Deployment commands and remote queries (parked messages, event logs) are routed to sites via Communication.
• Security & Auth: Authorization rules are enforced on every command using the authenticated user identity from the message envelope.
• Cluster Infrastructure: ManagementActor runs on all central nodes; ClusterClientReceptionist requires cluster membership.
• All service components: The ManagementActor delegates to the same services used by the Central UI — Template Engine, Deployment Manager, etc.

Interactions

• CLI: The primary consumer. Connects via Akka.NET ClusterClient and sends management messages to the ManagementActor.
• Host: Registers the ManagementActor and ClusterClientReceptionist on central nodes during startup.
• Central UI: Shares the same underlying services and repositories. The ManagementActor and Central UI are parallel interfaces to the same operations.
• Communication Layer: Deployment commands and remote site queries flow through communication actors.
• Configuration Database (via IAuditService): All configuration changes are audited.
• Security & Auth: The ManagementActor enforces authorization using user identity passed in messages. The CLI is responsible for authenticating the user and including their identity in every request.