# 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.