# 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](HighLevelReqs.md) — Complete high-level requirements covering all functional areas.

### Component Design Documents

| # | Component | Document | Description |
|---|-----------|----------|-------------|
| 1 | Template Engine | [Component-TemplateEngine.md](Component-TemplateEngine.md) | Template modeling, inheritance, composition, attribute resolution, locking, alarms, flattening, validation, and diff calculation. |
| 2 | Deployment Manager | [Component-DeploymentManager.md](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](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](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](Component-Communication.md) | Akka.NET remoting/cluster topology, message patterns, request routing, and debug streaming. |
| 6 | Store-and-Forward Engine | [Component-StoreAndForward.md](Component-StoreAndForward.md) | Buffering, retry, parking, application-level replication, and SQLite persistence at sites. |
| 7 | External System Gateway | [Component-ExternalSystemGateway.md](Component-ExternalSystemGateway.md) | External system definitions, API method invocation, and database connection management. |
| 8 | Notification Service | [Component-NotificationService.md](Component-NotificationService.md) | Notification lists, email delivery, script API, and store-and-forward integration. |
| 9 | Central UI | [Component-CentralUI.md](Component-CentralUI.md) | Web-based management interface, workflows, and pages. |
| 10 | Security & Auth | [Component-Security.md](Component-Security.md) | LDAP/AD authentication, role-based authorization, and site-scoped permissions. |
| 11 | Health Monitoring | [Component-HealthMonitoring.md](Component-HealthMonitoring.md) | Site health metrics collection (including alarm evaluation errors) and central reporting. |
| 12 | Site Event Logging | [Component-SiteEventLogging.md](Component-SiteEventLogging.md) | Local operational event logs at sites with central query access. |
| 13 | Cluster Infrastructure | [Component-ClusterInfrastructure.md](Component-ClusterInfrastructure.md) | Akka.NET cluster setup, active/standby failover, and node management. |
| 14 | Inbound API | [Component-InboundAPI.md](Component-InboundAPI.md) | Web API for external systems to call in, API key auth, method definitions, script-based implementations. |
| 15 | Host | [Component-Host.md](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](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](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
```