scadalink-design/CLAUDE.md

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.