SCADA System — Design Documentation

Overview

This document serves as the master index for the SCADA system design. The system is a centrally-managed, distributed SCADA configuration and deployment platform built on Akka.NET, running across a central cluster and multiple site clusters in a hub-and-spoke topology.

Document Map

Requirements

• HighLevelReqs.md — Complete high-level requirements covering all functional areas.

Component Design Documents

#	Component	Document	Description
1	Template Engine	Component-TemplateEngine.md	Template modeling, inheritance, composition, attribute resolution, locking, alarms, flattening, validation, and diff calculation.
2	Deployment Manager	Component-DeploymentManager.md	Central-side deployment pipeline: requesting configs, sending to sites, tracking status, system-wide artifact deployment, instance disable/delete.
3	Site Runtime	Component-SiteRuntime.md	Site-side actor hierarchy: Deployment Manager singleton, Instance Actors, Script Actors, Alarm Actors, script compilation, shared script library, and the site-wide attribute/alarm Akka stream.
4	Data Connection Layer	Component-DataConnectionLayer.md	Common data connection interface, OPC UA and custom protocol adapters, subscription management. Publishes tag value updates to Instance Actors.
5	Central–Site Communication	Component-Communication.md	Akka.NET remoting/cluster topology, message patterns, request routing, and debug streaming.
6	Store-and-Forward Engine	Component-StoreAndForward.md	Buffering, retry, parking, application-level replication, and SQLite persistence at sites.
7	External System Gateway	Component-ExternalSystemGateway.md	External system definitions, API method invocation, and database connection management.
8	Notification Service	Component-NotificationService.md	Notification lists, email delivery, script API, and store-and-forward integration.
9	Central UI	Component-CentralUI.md	Web-based management interface, workflows, and pages.
10	Security & Auth	Component-Security.md	LDAP/AD authentication, role-based authorization, and site-scoped permissions.
11	Health Monitoring	Component-HealthMonitoring.md	Site health metrics collection (including alarm evaluation errors) and central reporting.
12	Site Event Logging	Component-SiteEventLogging.md	Local operational event logs at sites with central query access.
13	Cluster Infrastructure	Component-ClusterInfrastructure.md	Akka.NET cluster setup, active/standby failover, and node management.
14	Inbound API	Component-InboundAPI.md	Web API for external systems to call in, API key auth, method definitions, script-based implementations.
15	Host	Component-Host.md	Single deployable binary, role-based component registration, Akka.NET bootstrap, and ASP.NET Core hosting for central nodes.
16	Commons	Component-Commons.md	Shared data types, interfaces, domain entity POCOs, repository interfaces, and message contracts used across all components.
17	Configuration Database	Component-ConfigurationDatabase.md	EF Core data access layer, schema ownership, per-component repositories, unit-of-work, audit logging (IAuditService), and migration management for the central MS SQL configuration database.

Architecture Diagram (Logical)

┌─────────────────────────────────────────────────────┐
│                   CENTRAL CLUSTER                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │ Template  │ │Deployment│ │ Central  │            │
│  │ Engine    │ │ Manager  │ │   UI     │            │
│  └──────────┘ └──────────┘ └──────────┘            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │ Security  │ │  Audit   │ │  Health  │            │
│  │ & Auth    │ │ Logging  │ │ Monitor  │            │
│  └──────────┘ └──────────┘ └──────────┘            │
│  ┌──────────┐                                       │
│  │ Inbound  │  ◄── External Systems (API key auth)  │
│  │   API    │                                       │
│  └──────────┘                                       │
│  ┌───────────────────────────────────┐              │
│  │    Akka.NET Communication Layer   │              │
│  └──────────────┬────────────────────┘              │
│  ┌───────────────────────────────────┐              │
│  │    Configuration Database (EF)    │──► MS SQL    │
│  └───────────────────────────────────┘   (Config DB)│
│                  │                    Machine Data DB│
└─────────────────┼───────────────────────────────────┘
                  │ Akka.NET Remoting
     ┌────────────┼────────────┐
     ▼            ▼            ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ SITE A  │ │ SITE B  │ │ SITE N  │
│ ┌─────┐ │ │ ┌─────┐ │ │ ┌─────┐ │
│ │Data │ │ │ │Data │ │ │ │Data │ │
│ │Conn │ │ │ │Conn │ │ │ │Conn │ │
│ ├─────┤ │ │ ├─────┤ │ │ ├─────┤ │
│ │Site │ │ │ │Site │ │ │ │Site │ │
│ │Runtm│ │ │ │Runtm│ │ │ │Runtm│ │
│ ├─────┤ │ │ ├─────┤ │ │ ├─────┤ │
│ │S&F  │ │ │ │S&F  │ │ │ │S&F  │ │
│ │Engine│ │ │ │Engine│ │ │ │Engine│ │
│ └─────┘ │ │ └─────┘ │ │ └─────┘ │
│ SQLite  │ │ SQLite  │ │ SQLite  │
└─────────┘ └─────────┘ └─────────┘

Site Runtime Actor Hierarchy

Deployment Manager Singleton (Cluster Singleton)
├── Instance Actor (one per deployed, enabled instance)
│   ├── Script Actor (coordinator, one per instance script)
│   │   └── Script Execution Actor (short-lived, per invocation)
│   ├── Alarm Actor (coordinator, one per alarm definition)
│   │   └── Alarm Execution Actor (short-lived, per on-trigger invocation)
│   └── ... (more Script/Alarm Actors)
├── Instance Actor
│   └── ...
└── ... (more Instance Actors)

Site-Wide Akka Stream (attribute + alarm state changes)
├── All Instance Actors publish to the stream
└── Debug view subscribes with instance-level filtering