80 lines
5.6 KiB
Markdown
80 lines
5.6 KiB
Markdown
# ScadaLink Design Documentation Project
|
||
|
||
This project contains design documentation for a distributed SCADA system built on Akka.NET. The documents describe a hub-and-spoke architecture with a central cluster and multiple site clusters.
|
||
|
||
## Project Structure
|
||
|
||
- `README.md` — Master index with component table and architecture diagrams.
|
||
- `HighLevelReqs.md` — Complete high-level requirements covering all functional areas.
|
||
- `Component-*.md` — Individual component design documents (one per component).
|
||
|
||
There is no source code in this project — only design documentation in markdown.
|
||
|
||
## Document Conventions
|
||
|
||
- All documents are markdown files in the project root directory.
|
||
- Component documents are named `Component-<Name>.md` (PascalCase, hyphen-separated).
|
||
- Each component document follows a consistent structure: Purpose, Location, Responsibilities, detailed design sections, Dependencies, and Interactions.
|
||
- The README.md component table must stay in sync with actual component documents. When a component is added, removed, or renamed, update the table.
|
||
- Cross-component references in Dependencies and Interactions sections must be kept accurate across all documents. When a component's role changes, update references in all affected documents.
|
||
|
||
## Refinement Process
|
||
|
||
- When refining requirements, use the Socratic method — ask clarifying questions before making changes.
|
||
- Probe for implications of decisions across components before updating documents.
|
||
- When a decision is made, identify all affected documents and update them together for consistency.
|
||
- After updates, verify no stale cross-references remain (e.g., references to removed or renamed components).
|
||
|
||
## Editing Rules
|
||
|
||
- Edit documents in place. Do not create copies or backup files.
|
||
- When a change affects multiple documents, update all affected documents in the same session.
|
||
- Use `git diff` to review changes before committing.
|
||
- Commit related changes together with a descriptive message summarizing the design decision.
|
||
|
||
## Current Component List (17 components)
|
||
|
||
1. Template Engine — Template modeling, inheritance, composition, validation, flattening, diffs.
|
||
2. Deployment Manager — Central-side deployment pipeline, system-wide artifact deployment, instance lifecycle.
|
||
3. Site Runtime — Site-side actor hierarchy (Deployment Manager singleton, Instance/Script/Alarm Actors), script compilation, Akka stream.
|
||
4. Data Connection Layer — Protocol abstraction (OPC UA, custom), subscription management, clean data pipe.
|
||
5. Central–Site Communication — Akka.NET remoting, message patterns, debug streaming.
|
||
6. Store-and-Forward Engine — Buffering, fixed-interval retry, parking, SQLite persistence, replication.
|
||
7. External System Gateway — External system definitions, API method invocation, database connections.
|
||
8. Notification Service — Notification lists, email delivery, store-and-forward integration.
|
||
9. Central UI — Web-based management interface, all workflows.
|
||
10. Security & Auth — LDAP/AD authentication, role-based authorization, site-scoped permissions.
|
||
11. Health Monitoring — Site health metrics collection and central reporting.
|
||
12. Site Event Logging — Local operational event logs at sites with central query access.
|
||
13. Cluster Infrastructure — Akka.NET cluster setup, active/standby failover, singleton support.
|
||
14. Inbound API — Web API for external systems, API key auth, script-based implementations.
|
||
15. Host — Single deployable binary, role-based component registration, Akka.NET bootstrap.
|
||
16. Commons — Shared types, POCO entity classes, repository interfaces, message contracts.
|
||
17. Configuration Database — EF Core data access layer, repositories, unit-of-work, audit logging (IAuditService), migrations.
|
||
|
||
## Key Design Decisions (for context across sessions)
|
||
|
||
- Instance modeled as Akka actor (Instance Actor) — single source of truth for runtime state.
|
||
- Site Runtime actor hierarchy: Deployment Manager singleton → Instance Actors → Script Actors + Alarm Actors.
|
||
- Script Actors spawn short-lived Script Execution Actors for concurrent execution.
|
||
- Alarm Actors are separate peer subsystem from scripts (not inside Script Engine).
|
||
- Shared scripts execute inline as compiled code (no separate actors).
|
||
- Site-wide Akka stream for attribute value and alarm state changes (debug view subscribes to this).
|
||
- Script Engine and Alarm Actors subscribe directly to Instance Actors (not via stream).
|
||
- Data Connection Layer is a clean data pipe — publishes to Instance Actors only.
|
||
- Pre-deployment validation is comprehensive (flattening, script compilation, trigger refs, binding completeness).
|
||
- Data source references are relative paths; connection binding is per-attribute at instance level.
|
||
- System-wide artifact deployment requires explicit Deployment role action.
|
||
- Store-and-forward: fixed retry interval, no max buffer size.
|
||
- Instance lifecycle: enabled/disabled states, deletion supported.
|
||
- Template deletion blocked if instances or child templates reference it.
|
||
- Naming collisions in composed feature modules are design-time errors.
|
||
- Last-write-wins for concurrent template editing.
|
||
- Scripts compiled at site; pre-validated (test compiled) at central.
|
||
- Max recursion depth for script-to-script calls.
|
||
- Alarm on-trigger scripts can call instance scripts; instance scripts cannot call alarm scripts.
|
||
- Audit logging absorbed into Configuration Database component (IAuditService).
|
||
- Entity classes are persistence-ignorant POCOs in Commons; EF mappings in Configuration Database.
|
||
- Repository interfaces defined in Commons; implementations in Configuration Database.
|
||
- EF Core migrations: auto-apply in dev, manual SQL scripts for production.
|