de636b908b
Notes and documentation covering actors, remoting, clustering, persistence, streams, serialization, hosting, testing, and best practices for the Akka.NET framework used throughout the ScadaLink system.
101 lines
6.2 KiB
Markdown
101 lines
6.2 KiB
Markdown
# 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](./AkkaComponents.md) | Master catalog of all Akka.NET components with documentation URLs |
|
||
| [BestPracticesAndTraps.md](./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](./01-Actors.md) | Actors (Core Library) | Actor-per-device model, supervision hierarchies, protocol abstraction |
|
||
| 2 | [02-Remoting.md](./02-Remoting.md) | Akka.Remote | Transport layer between the two failover nodes |
|
||
| 3 | [03-Cluster.md](./03-Cluster.md) | Akka.Cluster | 2-node membership, failure detection, split-brain resolution |
|
||
| 4 | [04-ClusterSharding.md](./04-ClusterSharding.md) | Cluster Sharding | Potential for distributing device actors (evaluated but may not apply) |
|
||
| 5 | [05-ClusterSingleton.md](./05-ClusterSingleton.md) | Cluster Singleton | Active node owns all device communication |
|
||
| 6 | [06-ClusterPubSub.md](./06-ClusterPubSub.md) | Cluster Publish-Subscribe | Event/alarm distribution between nodes |
|
||
| 7 | [07-ClusterMetrics.md](./07-ClusterMetrics.md) | Cluster Metrics | Node health monitoring |
|
||
| 8 | [08-Persistence.md](./08-Persistence.md) | Akka.Persistence | Command journal on SQLite for failover recovery |
|
||
| 9 | [09-DistributedData.md](./09-DistributedData.md) | Distributed Data | Cross-node state sync via CRDTs |
|
||
| 10 | [10-Streams.md](./10-Streams.md) | Akka.Streams | Tag subscription data flow, backpressure handling |
|
||
|
||
### Hosting & Integration
|
||
|
||
| # | Document | Component | Relevance to SCADA System |
|
||
|---|---|---|---|
|
||
| 11 | [11-Hosting.md](./11-Hosting.md) | Akka.Hosting | Microsoft.Extensions integration, DI, service lifecycle |
|
||
| 12 | [12-DependencyInjection.md](./12-DependencyInjection.md) | Akka.DependencyInjection | Injecting protocol adapters and services into actors |
|
||
|
||
### Discovery & Management
|
||
|
||
| # | Document | Component | Relevance to SCADA System |
|
||
|---|---|---|---|
|
||
| 13 | [13-Discovery.md](./13-Discovery.md) | Akka.Discovery | Node discovery in the failover pair |
|
||
| 14 | [14-Management.md](./14-Management.md) | Akka.Management | HTTP health endpoints, cluster bootstrap |
|
||
| 15 | [15-Coordination.md](./15-Coordination.md) | Akka.Coordination | Lease-based locking for singleton/SBR safety |
|
||
|
||
### Testing
|
||
|
||
| # | Document | Component | Relevance to SCADA System |
|
||
|---|---|---|---|
|
||
| 16 | [16-TestKit.md](./16-TestKit.md) | Akka.TestKit | Unit testing device actors and protocol logic |
|
||
| 17 | [17-HostingTestKit.md](./17-HostingTestKit.md) | Akka.Hosting.TestKit | Integration testing with full DI/hosting stack |
|
||
| 18 | [18-MultiNodeTestRunner.md](./18-MultiNodeTestRunner.md) | MultiNodeTestRunner | Failover scenario testing |
|
||
|
||
### Networking & Infrastructure
|
||
|
||
| # | Document | Component | Relevance to SCADA System |
|
||
|---|---|---|---|
|
||
| 19 | [19-AkkaIO.md](./19-AkkaIO.md) | Akka.IO | TCP/UDP communication with equipment |
|
||
| 20 | [20-Serialization.md](./20-Serialization.md) | Serialization | Message serialization for remoting and persistence |
|
||
| 21 | [21-Configuration.md](./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](./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](./BestPracticesAndTraps.md) for cross-cutting concerns and the production readiness checklist.
|