Files
scadalink-design/docs/plans/requirements-traceability.md
Joseph Doherty d91aa83665 refactor(docs): move requirements and test infra docs into docs/ subdirectories
Organize documentation by moving requirements (HighLevelReqs, Component-*,
lmxproxy_protocol) to docs/requirements/ and test infrastructure docs to
docs/test_infra/. Updates all cross-references in README, CLAUDE.md,
infra/README, component docs, and 23 plan files.
2026-03-21 01:11:35 -04:00

23 KiB
Raw Blame History

Requirements Traceability Matrix

Purpose: Ensures every requirement from docs/requirements/HighLevelReqs.md, every REQ-* identifier, and every design constraint from CLAUDE.md and docs/requirements/Component-*.md maps to at least one work package in an implementation phase plan. Updated as plan documents are generated.

Traceability levels:

  • Section-level (this document): Maps HighLevelReqs sections, REQ-* IDs, and design constraints to phases. Serves as the index.
  • Bullet-level (phase plan documents): Each phase plan contains a Requirements Checklist that decomposes its sections into individual bullets with [section-N] IDs, each mapped to a work package. The bullet-level detail lives in the plan documents, not here — this matrix tracks which sections are assigned and their verification status.

docs/requirements/HighLevelReqs.md Sections → Phase Mapping

Section Description Phase(s) Plan Document Status
1.1 Central vs. Site Responsibilities 3A phase-3a-runtime-foundation.md Phase 3A plan generated
1.2 Failover 3A, 3B, 3C, 8 phase-3a, phase-3b, phase-3c, phase-8 Phase 3A plan generated (mechanism)
1.3 Store-and-Forward Persistence 3C phase-3c-deployment-store-forward.md Pending
1.4 Deployment Behavior 3C, 6 phase-3c, phase-6 Phase 6 plan generated (UI portion)
1.5 System-Wide Artifact Deployment 3C, 6 phase-3c, phase-6 Phase 6 plan generated (UI portion)
2.1 Central Databases (MS SQL) 1 phase-1-central-foundations.md Pending
2.2 Communication: Central ↔ Site 3B phase-3b-site-io-observability.md Plan generated
2.3 Site-Level Storage & Interface 3A, 3B, 3C, 7 phase-3a, phase-3b, phase-3c, phase-7 Phase 3A plan generated (deployed configs)
2.4 Data Connection Protocols 3B phase-3b-site-io-observability.md Plan generated
2.5 Scale 8 phase-8-production-readiness.md Phase 8 plan generated
3.1 Template Structure 2 phase-2-modeling-validation.md Phase 2 plan generated
3.2 Attribute Definition 2 phase-2-modeling-validation.md Phase 2 plan generated
3.3 Data Connections 2, 3 phase-2, phase-3 Phase 2 plan generated (model/binding)
3.4 Alarm Definitions 2 phase-2-modeling-validation.md Phase 2 plan generated
3.4.1 Alarm State 3B phase-3b-site-io-observability.md Plan generated
3.5 Template Relationships 2 phase-2-modeling-validation.md Phase 2 plan generated
3.6 Locking 2 phase-2-modeling-validation.md Phase 2 plan generated
3.6 Attribute Resolution Order 2 phase-2-modeling-validation.md Phase 2 plan generated
3.7 Override Scope 2 phase-2-modeling-validation.md Phase 2 plan generated
3.8 Instance Rules 2 phase-2-modeling-validation.md Phase 2 plan generated
3.8.1 Instance Lifecycle 3C, 4 phase-3c, phase-4 Phase 4 planned — UI portion
3.9 Template Deployment & Change Propagation 2, 3C, 5, 6 phase-2, phase-3c, phase-5, phase-6 Phase 2 (diff/views), Phase 5 (last-write-wins UI), Phase 6 (deployment UI)
3.10 Areas 2, 4 phase-2, phase-4 Phase 2 planned (model), Phase 4 planned (UI)
3.11 Pre-Deployment Validation 2 phase-2-modeling-validation.md Phase 2 plan generated
4.1 Script Definitions 2, 3B phase-2, phase-3b Phase 2 plan generated (model), Phase 3B plan generated (runtime)
4.2 Script Triggers 3B phase-3b-site-io-observability.md Plan generated
4.3 Script Error Handling 3B phase-3b-site-io-observability.md Plan generated
4.4 Script Capabilities 3B, 7 phase-3b, phase-7 Phase 3B (core), Phase 7 plan generated (external/notify/DB)
4.4.1 Script Call Recursion Limit 3B phase-3b-site-io-observability.md Plan generated
4.5 Shared Scripts 2, 3B phase-2, phase-3b Phase 2 plan generated (model), Phase 3B plan generated (runtime)
4.6 Alarm On-Trigger Scripts 3B phase-3b-site-io-observability.md Plan generated
5.1 External System Definitions 5, 7 phase-5, phase-7 Phase 5 plan generated (UI), Phase 7 plan generated (runtime)
5.2 Site-to-External-System Communication 7 phase-7-integrations.md Phase 7 plan generated
5.3 Store-and-Forward for External Calls 3C, 7 phase-3c, phase-7 Phase 7 plan generated (integration)
5.4 Parked Message Management 3C, 6 phase-3c, phase-6 Phase 6 plan generated (UI)
5.5 Database Connections 5, 7 phase-5, phase-7 Phase 5 plan generated (UI), Phase 7 plan generated (runtime)
5.6 Database Access Modes 7 phase-7-integrations.md Phase 7 plan generated
6.1 Notification Lists 5, 7 phase-5, phase-7 Phase 5 plan generated (UI), Phase 7 plan generated (runtime)
6.2 Email Support 7 phase-7-integrations.md Phase 7 plan generated
6.3 Script API 7 phase-7-integrations.md Phase 7 plan generated
6.4 Store-and-Forward for Notifications 7 phase-7-integrations.md Phase 7 plan generated
7.1 Inbound API Purpose 7 phase-7-integrations.md Phase 7 plan generated
7.2 API Key Management 4 phase-4-operator-ui.md Planned — bullet-level in plan
7.3 Inbound API Authentication 7 phase-7-integrations.md Phase 7 plan generated
7.4 API Method Definitions 5, 7 phase-5, phase-7 Phase 5 plan generated (UI), Phase 7 plan generated (runtime)
7.5 Inbound API Availability 7 phase-7-integrations.md Phase 7 plan generated
8 Central UI (all workflows) 4, 5, 6 phase-4, phase-5, phase-6 Phase 4 planned, Phase 5 plan generated, Phase 6 plan generated
8.1 Debug View 3B, 6 phase-3b, phase-6 Phase 3B plan generated (backend), Phase 6 plan generated (UI)
9.1 Authentication 1 phase-1-central-foundations.md Pending
9.2 Authorization 1 phase-1-central-foundations.md Pending
9.3 Roles 1 phase-1-central-foundations.md Pending
9.4 Role Scoping 1 phase-1-central-foundations.md Pending
10.1 Audit Storage 1 phase-1-central-foundations.md Pending
10.2 Audit Scope 1 phase-1-central-foundations.md Pending
10.3 Audit Detail Level 1 phase-1-central-foundations.md Pending
10.4 Audit Transactional Guarantee 1 phase-1-central-foundations.md Pending
11.1 Monitored Metrics 3B phase-3b-site-io-observability.md Plan generated
11.2 Health Reporting 3B phase-3b-site-io-observability.md Plan generated
12.1 Events Logged 3B phase-3b-site-io-observability.md Plan generated
12.2 Event Log Storage 3B phase-3b-site-io-observability.md Plan generated
12.3 Central Access to Event Logs 3B, 6 phase-3b, phase-6 Phase 3B plan generated (backend query)
13.1 Timestamps (UTC) 0 phase-0-solution-skeleton.md Plan generated

REQ-* Identifiers → Phase Mapping

REQ ID Component Description Phase(s) Status
REQ-COM-1 Commons Shared Data Type System 0 Plan generated (Phase 0)
REQ-COM-2 Commons Protocol Abstraction (IDataConnection) 0, 3 Plan generated (Phase 0: interface)
REQ-COM-3 Commons Domain Entity Classes (POCOs) 0 Plan generated (Phase 0)
REQ-COM-4 Commons Per-Component Repository Interfaces 0 Plan generated (Phase 0)
REQ-COM-4a Commons Cross-Cutting Service Interfaces (IAuditService) 0, 1 Plan generated (Phase 0: interface)
REQ-COM-5 Commons Cross-Component Message Contracts 0 Plan generated (Phase 0)
REQ-COM-5a Commons Message Contract Versioning 0 Plan generated (Phase 0)
REQ-COM-5b Commons Namespace & Folder Convention 0 Plan generated (Phase 0)
REQ-COM-6 Commons No Business Logic 0 Plan generated (Phase 0)
REQ-COM-7 Commons Minimal Dependencies 0 Plan generated (Phase 0)
REQ-HOST-1 Host Single Binary Deployment 0 Plan generated (Phase 0)
REQ-HOST-2 Host Role-Based Service Registration 0, 1 Plan generated (Phase 0: skeleton)
REQ-HOST-3 Host Configuration Binding (Options pattern) 0, 1 Plan generated (Phase 0: skeleton)
REQ-HOST-4 Host Startup Validation 1 Pending
REQ-HOST-4a Host Readiness Gating 1 Pending
REQ-HOST-5 Host Windows Service Hosting 1 Pending
REQ-HOST-6 Host Akka.NET Bootstrap 1, 3A Phase 3A plan generated (site-role)
REQ-HOST-7 Host ASP.NET Web Endpoints (Central Only) 1 Pending
REQ-HOST-8 Host Structured Logging (Serilog) 1 Pending
REQ-HOST-8a Host Dead Letter Monitoring 1 Pending
REQ-HOST-9 Host Graceful Shutdown (CoordinatedShutdown) 1 Pending
REQ-HOST-10 Host Extension Method Convention 0 Plan generated (Phase 0)

Design Constraints → Phase Mapping

Design decisions from CLAUDE.md Key Design Decisions and docs/requirements/Component-*.md documents that impose implementation constraints beyond what docs/requirements/HighLevelReqs specifies. Each is tagged [KDD-category-N] (Key Design Decision) or [CD-Component-N] (Component Design). Bullet-level extraction happens in the phase plan documents.

Architecture & Runtime

ID Constraint Source Phase(s) Status
KDD-runtime-1 Instance modeled as Akka actor (Instance Actor) — single source of truth for runtime state CLAUDE.md 3A Phase 3A plan generated
KDD-runtime-2 Site Runtime actor hierarchy: Deployment Manager singleton → Instance Actors → Script Actors + Alarm Actors CLAUDE.md 3A, 3B Phase 3A plan generated (DM→IA)
KDD-runtime-3 Script Actors spawn short-lived Script Execution Actors on dedicated blocking I/O dispatcher CLAUDE.md 3B Plan generated
KDD-runtime-4 Alarm Actors are separate peer subsystem from scripts CLAUDE.md 3B Plan generated
KDD-runtime-5 Shared scripts execute inline as compiled code (no separate actors) CLAUDE.md 3B Plan generated
KDD-runtime-6 Site-wide Akka stream for attribute value and alarm state changes with per-subscriber buffering CLAUDE.md 3B Plan generated
KDD-runtime-7 Instance Actors serialize all state mutations; concurrent scripts produce interleaved side effects CLAUDE.md 3B Plan generated
KDD-runtime-8 Staggered Instance Actor startup on failover to prevent reconnection storms CLAUDE.md 3A Phase 3A plan generated
KDD-runtime-9 Supervision: Resume for coordinator actors, Stop for short-lived execution actors CLAUDE.md 3A, 3B Phase 3A plan generated (Resume)

Data & Communication

ID Constraint Source Phase(s) Status
KDD-data-1 DCL connection actor uses Become/Stash pattern for lifecycle state machine CLAUDE.md, Component-DCL 3B Plan generated
KDD-data-2 DCL auto-reconnect at fixed interval; immediate bad quality on disconnect; transparent re-subscribe CLAUDE.md, Component-DCL 3B Plan generated
KDD-data-3 DCL write failures returned synchronously to calling script CLAUDE.md, Component-DCL 3B Plan generated
KDD-data-4 Tag path resolution retried periodically for devices still booting CLAUDE.md, Component-DCL 3B Plan generated
KDD-data-5 Static attribute writes persisted to local SQLite (survive restart/failover, reset on redeployment) CLAUDE.md 3A Phase 3A plan generated
KDD-data-6 All timestamps are UTC throughout the system CLAUDE.md 0 Plan generated (Phase 0)
KDD-data-7 Tell for hot-path internal communication; Ask reserved for system boundaries CLAUDE.md 3A, 3B Phase 3A plan generated (Tell)
KDD-data-8 Application-level correlation IDs on all request/response messages CLAUDE.md 3B Plan generated

External Integrations

ID Constraint Source Phase(s) Status
KDD-ext-1 External System Gateway: HTTP/REST only, JSON serialization, API key + Basic Auth CLAUDE.md 7 Phase 7 plan generated
KDD-ext-2 Dual call modes: Call() synchronous and CachedCall() store-and-forward CLAUDE.md 7 Phase 7 plan generated
KDD-ext-3 Error classification: HTTP 5xx/408/429/connection = transient; other 4xx = permanent CLAUDE.md 7 Phase 7 plan generated
KDD-ext-4 Notification Service: SMTP with OAuth2 Client Credentials (M365) or Basic Auth. BCC delivery, plain text CLAUDE.md 7 Phase 7 plan generated
KDD-ext-5 Inbound API: POST /api/{methodName}, X-API-Key header, flat JSON, extended type system CLAUDE.md 7 Phase 7 plan generated

Templates & Deployment

ID Constraint Source Phase(s) Status
KDD-deploy-1 Pre-deployment validation includes semantic checks (call targets, argument types, trigger operand types) CLAUDE.md 2 Plan generated
KDD-deploy-2 Composed member addressing: [ModuleInstanceName].[MemberName] CLAUDE.md 2 Plan generated
KDD-deploy-3 Override granularity defined per entity type and per field CLAUDE.md 2 Plan generated
KDD-deploy-4 Template graph acyclicity enforced on save CLAUDE.md 2 Plan generated
KDD-deploy-5 Flattened configs include revision hash for staleness detection CLAUDE.md 2 Plan generated
KDD-deploy-6 Deployment identity: unique deployment ID + revision hash for idempotency CLAUDE.md 3C Pending
KDD-deploy-7 Per-instance operation lock covers all mutating commands CLAUDE.md 3C Pending
KDD-deploy-8 Site-side apply is all-or-nothing per instance CLAUDE.md 3C Pending
KDD-deploy-9 System-wide artifact version skew across sites is supported CLAUDE.md 3C Pending
KDD-deploy-10 Last-write-wins for concurrent template editing CLAUDE.md 2 Plan generated
KDD-deploy-11 Optimistic concurrency on deployment status records CLAUDE.md 3C Pending
KDD-deploy-12 Naming collisions in composed feature modules are design-time errors CLAUDE.md 2 Plan generated

Store-and-Forward

ID Constraint Source Phase(s) Status
KDD-sf-1 Fixed retry interval, no max buffer size. Only transient failures buffered CLAUDE.md 3C Pending
KDD-sf-2 Async best-effort replication to standby (no ack wait) CLAUDE.md 3C Pending
KDD-sf-3 Messages not cleared on instance deletion CLAUDE.md 3C Pending
KDD-sf-4 CachedCall idempotency is the caller's responsibility CLAUDE.md 7 Phase 7 plan generated

Security & Auth

ID Constraint Source Phase(s) Status
KDD-sec-1 Authentication: direct LDAP bind, no Kerberos/NTLM. LDAPS/StartTLS required CLAUDE.md 1 Pending
KDD-sec-2 JWT: HMAC-SHA256 shared symmetric key, 15-min expiry with sliding refresh, 30-min idle timeout CLAUDE.md 1 Pending
KDD-sec-3 LDAP failure: new logins fail; active sessions continue with current roles CLAUDE.md 1 Pending
KDD-sec-4 Load balancer in front of central UI; JWT + shared Data Protection keys for failover CLAUDE.md 1 Pending

Cluster & Failover

ID Constraint Source Phase(s) Status
KDD-cluster-1 Keep-oldest SBR with down-if-alone=on, 15s stable-after CLAUDE.md 3A Phase 3A plan generated
KDD-cluster-2 Both nodes are seed nodes. min-nr-of-members=1 CLAUDE.md 3A Phase 3A plan generated
KDD-cluster-3 Failure detection: 2s heartbeat, 10s threshold. Total failover ~25s CLAUDE.md 3A Phase 3A plan generated
KDD-cluster-4 CoordinatedShutdown for graceful singleton handover CLAUDE.md 3A Phase 3A plan generated
KDD-cluster-5 Automatic dual-node recovery from persistent storage CLAUDE.md 3A Phase 3A plan generated

UI & Monitoring

ID Constraint Source Phase(s) Status
KDD-ui-1 Central UI: Blazor Server (ASP.NET Core + SignalR) CLAUDE.md 1 Pending
KDD-ui-2 Real-time push for debug view, health dashboard, deployment status CLAUDE.md 3B, 6 Phase 3B plan generated (backend streaming)
KDD-ui-3 Health reports: 30s interval, 60s offline threshold, monotonic sequence numbers, raw error counts CLAUDE.md 3B Plan generated
KDD-ui-4 Dead letter monitoring as health metric CLAUDE.md 3B Plan generated
KDD-ui-5 Site Event Logging: 30-day retention, 1GB cap, daily purge, paginated queries with keyword search CLAUDE.md 3B Plan generated

Code Organization

ID Constraint Source Phase(s) Status
KDD-code-1 Entity classes are persistence-ignorant POCOs in Commons; EF mappings in Configuration Database CLAUDE.md 0, 1 Plan generated (Phase 0: POCOs)
KDD-code-2 Repository interfaces in Commons; implementations in Configuration Database CLAUDE.md 0, 1 Plan generated (Phase 0: interfaces)
KDD-code-3 Commons namespace hierarchy: Types/, Interfaces/, Entities/, Messages/ with domain area subfolders CLAUDE.md 0 Plan generated (Phase 0)
KDD-code-4 Message contracts follow additive-only evolution rules CLAUDE.md 0 Plan generated (Phase 0)
KDD-code-5 Per-component configuration via appsettings.json sections bound to options classes CLAUDE.md 0, 1 Plan generated (Phase 0: skeleton)
KDD-code-6 Options classes owned by component projects, not Commons CLAUDE.md 0 Plan generated (Phase 0)
KDD-code-7 Host readiness gating: /health/ready endpoint, no traffic until operational CLAUDE.md 1 Pending
KDD-code-8 EF Core migrations: auto-apply in dev, manual SQL scripts for production CLAUDE.md 1 Pending
KDD-code-9 Script trust model: forbidden APIs (System.IO, Process, Threading, Reflection, raw network) CLAUDE.md 3B Plan generated

LmxProxy Protocol (Component Design)

ID Constraint Source Phase(s) Status
CD-DCL-1 LmxProxy: gRPC/HTTP/2 transport, protobuf-net code-first, port 5050 Component-DCL 3B Plan generated
CD-DCL-2 LmxProxy: API key auth, session-based (SessionId), 30s keep-alive heartbeat Component-DCL 3B Plan generated
CD-DCL-3 LmxProxy: Server-streaming gRPC for subscriptions, 1000ms default sampling Component-DCL 3B Plan generated
CD-DCL-4 LmxProxy: SDK retry policy (exponential backoff) complements DCL.s fixed-interval reconnect Component-DCL 3B Plan generated
CD-DCL-5 LmxProxy: Batch read/write capabilities (ReadBatchAsync, WriteBatchAsync) Component-DCL 3B Plan generated
CD-DCL-6 LmxProxy: TLS 1.2/1.3, mutual TLS, self-signed for dev Component-DCL 3B Plan generated

Split-Section Tracking

Sections that span multiple phases. When phase plans are generated, this table tracks which bullets each phase owns. The union must equal the full section — no gaps.

Section Description Phase Split Bullet-Level Verified
1.2 Failover 3A (singleton migration, cluster config), 3B (DCL/scripts), 3C (S&F takeover), 8 (full-system) Phase 3A: [1.2-1][1.2-4] mechanism. Phase 3B/3C/8: completion.
1.4 Deployment Behavior 3C (pipeline), 6 (UI) Phase 3C: backend pipeline (pending). Phase 6: [1.4-1-ui], [1.4-3-ui], [1.4-4-ui] UI. Phase 6 verified.
1.5 System-Wide Artifact Deployment 3C (backend), 6 (UI) Phase 3C: backend (pending). Phase 6: [1.5-1-ui][1.5-3-ui] UI. Phase 6 verified.
3.3 Data Connections 2 (model/binding), 3B (runtime) Phase 2: [3.3-1][3.3-9] model/binding. Phase 3B: runtime protocol/subscription.
3.8.1 Instance Lifecycle 3C (backend), 4 (UI) Phase 4 planned: [3.8.1-ui-1][3.8.1-ui-3]. Phase 3C: pending.
3.9 Deployment & Change Propagation 2 (diff/views), 3C (pipeline), 5 (last-write-wins UI), 6 (deployment UI) Phase 2: [3.9-1][3.9-5] diff/views. Phase 3C: pipeline (pending). Phase 5: [3.9-6] last-write-wins UI. Phase 6: [3.9-1-ui][3.9-5-ui] deployment UI. Phases 5, 6 verified.
3.10 Areas 2 (model), 4 (UI) Phase 2: [3.10-1][3.10-4] model/hierarchy. Phase 4: Admin UI management.
4.1 Script Definitions 2 (model), 3B (runtime) Phase 2: [4.1-1][4.1-7] model/params/return. Phase 3B: triggers/runtime/execution.
4.5 Shared Scripts 2 (model), 3B (runtime) Phase 2: [4.5-1][4.5-3] model/CRUD/validation. Phase 3B: deployment/execution.
4.4 Script Capabilities 3B (core: read/write/call), 7 (external/notify/DB) Phase 3B: [4.4-1][4.4-5], [4.4-10]. Phase 7: [4.4-6][4.4-9]. Phase 7 verified.
5.1 External System Definitions 5 (UI), 7 (runtime) Phase 5: [5.1-1][5.1-5] definition UI. Phase 7: [5.1-1-rt], [5.1-2-rt] runtime. Verified.
5.3 S&F for External Calls 3C (engine), 7 (integration) Phase 3C: engine (pending). Phase 7: [5.3-1-int][5.3-5-int] integration. Phase 7 verified.
5.4 Parked Message Management 3C (backend), 6 (UI) Phase 3C: backend (pending). Phase 6: [5.4-1-ui][5.4-4-ui] UI. Phase 6 verified.
5.5 Database Connections 5 (UI), 7 (runtime) Phase 5: [5.5-1][5.5-5] definition UI. Phase 7: [5.5-1-rt], [5.5-2-rt], [5.6-1][5.6-6] runtime. Verified.
6.1 Notification Lists 5 (UI), 7 (runtime) Phase 5: [6.1-1][6.1-5] definition UI. Phase 7: [6.1-1-rt], [6.1-2-rt] runtime. Verified.
7.4 API Method Definitions 5 (UI), 7 (runtime) Phase 5: [7.4-1][7.4-8] definition UI. Phase 7: [7.4-1-rt][7.4-8-rt] runtime. Verified.
8 Central UI 4, 5, 6 (split by workflow type) Phase 4: admin/operator. Phase 5: [8-design-1][8-design-10] design. Phase 6: [8-deploy-1][8-deploy-8] deployment/troubleshooting. Phases 5, 6 verified.

Coverage Verification

HighLevelReqs sections: 54 sections mapped. 0 unmapped. REQ- identifiers*: 22 identifiers mapped. 0 unmapped. Design constraints (KDD-*): 52 constraints mapped. 0 unmapped. Component design constraints (CD-*): 6 constraints mapped. 0 unmapped. Split sections: 16 identified. 12 bullet-level verified (Phases 5, 6, 7, 8 generated in this session; earlier phases partially verified). Remaining: 3.8.1 (Phase 3C pending), 1.4/1.5/5.3/5.4 (Phase 3C portions pending).

All requirements and constraints have at least one phase assignment. Bullet-level verification occurs during phase plan generation — each plan document contains its own Requirements Checklist and Design Constraints Checklist with forward/reverse tracing to work packages.