Initial design docs from claude.ai refinement sessions
This commit is contained in:
Joseph Doherty
95
README.md
Normal file
95
README.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user