cd03b77913
Define POST /api/{methodName} URL structure with X-API-Key header. Flat JSON
request/response with no envelope wrapper. Add extended type system (Object, List)
for complex API parameters and return values, applied to both Inbound API and
External System Gateway method definitions. Only failures logged; no rate limiting
in this controlled industrial environment.
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