scadalink-design/AkkaDotNet/README.md

Akka.NET SCADA System — Architecture & Design Knowledge Base

System Overview

This knowledge base documents the architectural design decisions for an industrial SCADA system built on Akka.NET. The system manages communication with 50–500 machines per site using a unified protocol abstraction layer (OPC-UA and a custom legacy SCADA protocol), deployed as 2-node active/cold-standby failover pairs on Windows Server.

Key Architectural Constraints

• Platform: Windows Server, .NET 10, C#
• Cluster Topology: Exactly 2 nodes per site — active/cold-standby
• Equipment Scale: 50–500 machines per site
• Protocols: OPC-UA and a custom legacy SCADA protocol, both supporting tag subscriptions; unified behind a common high-level comms abstraction
• Consistency Requirement: No commands lost or duplicated during failover
• Persistence: Akka.Persistence on SQLite (no SQL Server guaranteed at every site), synced between nodes via Akka.NET distributed mechanisms
• Database: MS SQL Server used where available (historian, reporting); not the persistence journal
• Failover Model: Cold standby — standby node is idle until failover, then recovers state via Akka.Persistence journal and re-reads from equipment

Core Architectural Patterns

Pattern	Akka.NET Component	Purpose
Actor-per-device	Actors (Core)	Each machine is represented by a dedicated actor
Protocol abstraction	Actors (Core) + Akka.IO/Streams	Common comms interface with OPC-UA and custom protocol implementations
Active node ownership	Cluster Singleton	Only the active node owns device communication
Command recovery	Akka.Persistence (SQLite)	In-flight command journal for failover recovery
Cross-node state sync	Distributed Data	Lightweight state replication between the pair
2-node split-brain safety	Cluster (SBR)	Keep-oldest or lease-based strategy for the 2-node edge case

---

Document Index

Reference Catalog

Document	Description
AkkaComponents.md	Master catalog of all Akka.NET components with documentation URLs
BestPracticesAndTraps.md	Cross-cutting best practices, common traps, and a production readiness checklist

Core Components

#	Document	Component	Relevance to SCADA System
1	01-Actors.md	Actors (Core Library)	Actor-per-device model, supervision hierarchies, protocol abstraction
2	02-Remoting.md	Akka.Remote	Transport layer between the two failover nodes
3	03-Cluster.md	Akka.Cluster	2-node membership, failure detection, split-brain resolution
4	04-ClusterSharding.md	Cluster Sharding	Potential for distributing device actors (evaluated but may not apply)
5	05-ClusterSingleton.md	Cluster Singleton	Active node owns all device communication
6	06-ClusterPubSub.md	Cluster Publish-Subscribe	Event/alarm distribution between nodes
7	07-ClusterMetrics.md	Cluster Metrics	Node health monitoring
8	08-Persistence.md	Akka.Persistence	Command journal on SQLite for failover recovery
9	09-DistributedData.md	Distributed Data	Cross-node state sync via CRDTs
10	10-Streams.md	Akka.Streams	Tag subscription data flow, backpressure handling

Hosting & Integration

#	Document	Component	Relevance to SCADA System
11	11-Hosting.md	Akka.Hosting	Microsoft.Extensions integration, DI, service lifecycle
12	12-DependencyInjection.md	Akka.DependencyInjection	Injecting protocol adapters and services into actors

Discovery & Management

#	Document	Component	Relevance to SCADA System
13	13-Discovery.md	Akka.Discovery	Node discovery in the failover pair
14	14-Management.md	Akka.Management	HTTP health endpoints, cluster bootstrap
15	15-Coordination.md	Akka.Coordination	Lease-based locking for singleton/SBR safety

Testing

#	Document	Component	Relevance to SCADA System
16	16-TestKit.md	Akka.TestKit	Unit testing device actors and protocol logic
17	17-HostingTestKit.md	Akka.Hosting.TestKit	Integration testing with full DI/hosting stack
18	18-MultiNodeTestRunner.md	MultiNodeTestRunner	Failover scenario testing

Networking & Infrastructure

#	Document	Component	Relevance to SCADA System
19	19-AkkaIO.md	Akka.IO	TCP/UDP communication with equipment
20	20-Serialization.md	Serialization	Message serialization for remoting and persistence
21	21-Configuration.md	HOCON Configuration	System configuration management

---

How to Use This Knowledge Base

Each component document follows a consistent structure:

1. Overview — What the component does and its role in the SCADA system
2. When to Use / When Not to Use — Decision criteria for this system
3. Design Decisions — Architectural choices specific to our failover-pair SCADA topology
4. Common Patterns — Recommended usage patterns for our context
5. Anti-Patterns — What to avoid and why
6. Configuration Guidance — Key settings with recommended values for our deployment
7. References — Links to official documentation

Start with the AkkaComponents.md for a broad overview, then read the core components (1–10) for the primary architectural decisions. The hosting/integration docs (11–12) cover how the system boots and wires together. Testing docs (16–18) cover validation strategy. Before going to production, review BestPracticesAndTraps.md for cross-cutting concerns and the production readiness checklist.