a9fa74d5ac
- Replace "custom protocol" placeholder with full LmxProxy details (gRPC transport, SDK API mapping, session management, keep-alive, TLS, batch ops) - Add bullet-level requirement traceability, design constraint traceability (52 KDD + 6 CD), split-section tracking, and post-generation orphan check to plan framework - Resolve Q9 (LmxProxy), Q11 (REST test server), Q13 (solo dev), Q14 (self-test), Q15 (Machine Data DB out of scope) - Set Central UI constraints: Blazor Server + Bootstrap only, no heavy frameworks, custom components, clean corporate design
19 KiB
19 KiB
Requirements Traceability Matrix
Purpose: Ensures every requirement from HighLevelReqs.md, every REQ-* identifier, and every design constraint from CLAUDE.md and 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.
HighLevelReqs.md Sections → Phase Mapping
| Section | Description | Phase(s) | Plan Document | Status |
|---|---|---|---|---|
| 1.1 | Central vs. Site Responsibilities | 3A | phase-3a-runtime-foundation.md | Pending |
| 1.2 | Failover | 3A, 8 | phase-3a, phase-8 | Pending |
| 1.3 | Store-and-Forward Persistence | 3C | phase-3c-deployment-store-forward.md | Pending |
| 1.4 | Deployment Behavior | 3C, 6 | phase-3c, phase-6 | Pending |
| 1.5 | System-Wide Artifact Deployment | 3C, 6 | phase-3c, phase-6 | Pending |
| 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 | Pending |
| 2.3 | Site-Level Storage & Interface | 3A | phase-3a-runtime-foundation.md | Pending |
| 2.4 | Data Connection Protocols | 3B | phase-3b-site-io-observability.md | Pending |
| 2.5 | Scale | 8 | phase-8-production-readiness.md | Pending |
| 3.1 | Template Structure | 2 | phase-2-modeling-validation.md | Pending |
| 3.2 | Attribute Definition | 2 | phase-2-modeling-validation.md | Pending |
| 3.3 | Data Connections | 2, 3 | phase-2, phase-3 | Pending |
| 3.4 | Alarm Definitions | 2 | phase-2-modeling-validation.md | Pending |
| 3.4.1 | Alarm State | 3B | phase-3b-site-io-observability.md | Pending |
| 3.5 | Template Relationships | 2 | phase-2-modeling-validation.md | Pending |
| 3.6 | Locking | 2 | phase-2-modeling-validation.md | Pending |
| 3.6 | Attribute Resolution Order | 2 | phase-2-modeling-validation.md | Pending |
| 3.7 | Override Scope | 2 | phase-2-modeling-validation.md | Pending |
| 3.8 | Instance Rules | 2 | phase-2-modeling-validation.md | Pending |
| 3.8.1 | Instance Lifecycle | 3C, 4 | phase-3c, phase-4 | Pending |
| 3.9 | Template Deployment & Change Propagation | 3C, 6 | phase-3c, phase-6 | Pending |
| 3.10 | Areas | 2, 4 | phase-2, phase-4 | Pending |
| 3.11 | Pre-Deployment Validation | 2 | phase-2-modeling-validation.md | Pending |
| 4.1 | Script Definitions | 2, 3B | phase-2, phase-3b | Pending |
| 4.2 | Script Triggers | 3B | phase-3b-site-io-observability.md | Pending |
| 4.3 | Script Error Handling | 3B | phase-3b-site-io-observability.md | Pending |
| 4.4 | Script Capabilities | 3B, 7 | phase-3b, phase-7 | Pending |
| 4.4.1 | Script Call Recursion Limit | 3B | phase-3b-site-io-observability.md | Pending |
| 4.5 | Shared Scripts | 3B | phase-3b-site-io-observability.md | Pending |
| 4.6 | Alarm On-Trigger Scripts | 3B | phase-3b-site-io-observability.md | Pending |
| 5.1 | External System Definitions | 5, 7 | phase-5, phase-7 | Pending |
| 5.2 | Site-to-External-System Communication | 7 | phase-7-integrations.md | Pending |
| 5.3 | Store-and-Forward for External Calls | 3C, 7 | phase-3c, phase-7 | Pending |
| 5.4 | Parked Message Management | 3C, 6 | phase-3c, phase-6 | Pending |
| 5.5 | Database Connections | 5, 7 | phase-5, phase-7 | Pending |
| 5.6 | Database Access Modes | 7 | phase-7-integrations.md | Pending |
| 6.1 | Notification Lists | 5, 7 | phase-5, phase-7 | Pending |
| 6.2 | Email Support | 7 | phase-7-integrations.md | Pending |
| 6.3 | Script API | 7 | phase-7-integrations.md | Pending |
| 6.4 | Store-and-Forward for Notifications | 7 | phase-7-integrations.md | Pending |
| 7.1 | Inbound API Purpose | 7 | phase-7-integrations.md | Pending |
| 7.2 | API Key Management | 4 | phase-4-operator-ui.md | Pending |
| 7.3 | Inbound API Authentication | 7 | phase-7-integrations.md | Pending |
| 7.4 | API Method Definitions | 5, 7 | phase-5, phase-7 | Pending |
| 7.5 | Inbound API Availability | 7 | phase-7-integrations.md | Pending |
| 8 | Central UI (all workflows) | 4, 5, 6 | phase-4, phase-5, phase-6 | Pending |
| 8.1 | Debug View | 6 | phase-6-deployment-ops-ui.md | Pending |
| 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 | Pending |
| 11.2 | Health Reporting | 3B | phase-3b-site-io-observability.md | Pending |
| 12.1 | Events Logged | 3B | phase-3b-site-io-observability.md | Pending |
| 12.2 | Event Log Storage | 3B | phase-3b-site-io-observability.md | Pending |
| 12.3 | Central Access to Event Logs | 6 | phase-6-deployment-ops-ui.md | Pending |
| 13.1 | Timestamps (UTC) | 0 | phase-0-solution-skeleton.md | Pending |
REQ-* Identifiers → Phase Mapping
| REQ ID | Component | Description | Phase(s) | Status |
|---|---|---|---|---|
| REQ-COM-1 | Commons | Shared Data Type System | 0 | Pending |
| REQ-COM-2 | Commons | Protocol Abstraction (IDataConnection) | 0, 3 | Pending |
| REQ-COM-3 | Commons | Domain Entity Classes (POCOs) | 0 | Pending |
| REQ-COM-4 | Commons | Per-Component Repository Interfaces | 0 | Pending |
| REQ-COM-4a | Commons | Cross-Cutting Service Interfaces (IAuditService) | 0, 1 | Pending |
| REQ-COM-5 | Commons | Cross-Component Message Contracts | 0 | Pending |
| REQ-COM-5a | Commons | Message Contract Versioning | 0 | Pending |
| REQ-COM-5b | Commons | Namespace & Folder Convention | 0 | Pending |
| REQ-COM-6 | Commons | No Business Logic | 0 | Pending |
| REQ-COM-7 | Commons | Minimal Dependencies | 0 | Pending |
| REQ-HOST-1 | Host | Single Binary Deployment | 0 | Pending |
| REQ-HOST-2 | Host | Role-Based Service Registration | 0, 1 | Pending |
| REQ-HOST-3 | Host | Configuration Binding (Options pattern) | 0, 1 | Pending |
| 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 | Pending |
| 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 | Pending |
Design Constraints → Phase Mapping
Design decisions from CLAUDE.md Key Design Decisions and Component-*.md documents that impose implementation constraints beyond what 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 | Pending |
| KDD-runtime-2 | Site Runtime actor hierarchy: Deployment Manager singleton → Instance Actors → Script Actors + Alarm Actors | CLAUDE.md | 3A, 3B | Pending |
| KDD-runtime-3 | Script Actors spawn short-lived Script Execution Actors on dedicated blocking I/O dispatcher | CLAUDE.md | 3B | Pending |
| KDD-runtime-4 | Alarm Actors are separate peer subsystem from scripts | CLAUDE.md | 3B | Pending |
| KDD-runtime-5 | Shared scripts execute inline as compiled code (no separate actors) | CLAUDE.md | 3B | Pending |
| KDD-runtime-6 | Site-wide Akka stream for attribute value and alarm state changes with per-subscriber buffering | CLAUDE.md | 3B | Pending |
| KDD-runtime-7 | Instance Actors serialize all state mutations; concurrent scripts produce interleaved side effects | CLAUDE.md | 3B | Pending |
| KDD-runtime-8 | Staggered Instance Actor startup on failover to prevent reconnection storms | CLAUDE.md | 3A | Pending |
| KDD-runtime-9 | Supervision: Resume for coordinator actors, Stop for short-lived execution actors | CLAUDE.md | 3A | Pending |
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 | Pending |
| KDD-data-2 | DCL auto-reconnect at fixed interval; immediate bad quality on disconnect; transparent re-subscribe | CLAUDE.md, Component-DCL | 3B | Pending |
| KDD-data-3 | DCL write failures returned synchronously to calling script | CLAUDE.md, Component-DCL | 3B | Pending |
| KDD-data-4 | Tag path resolution retried periodically for devices still booting | CLAUDE.md, Component-DCL | 3B | Pending |
| KDD-data-5 | Static attribute writes persisted to local SQLite (survive restart/failover, reset on redeployment) | CLAUDE.md | 3A | Pending |
| KDD-data-6 | All timestamps are UTC throughout the system | CLAUDE.md | 0 | Pending |
| KDD-data-7 | Tell for hot-path internal communication; Ask reserved for system boundaries | CLAUDE.md | 3A, 3B | Pending |
| KDD-data-8 | Application-level correlation IDs on all request/response messages | CLAUDE.md | 3B | Pending |
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 | Pending |
| KDD-ext-2 | Dual call modes: Call() synchronous and CachedCall() store-and-forward | CLAUDE.md | 7 | Pending |
| KDD-ext-3 | Error classification: HTTP 5xx/408/429/connection = transient; other 4xx = permanent | CLAUDE.md | 7 | Pending |
| KDD-ext-4 | Notification Service: SMTP with OAuth2 Client Credentials (M365) or Basic Auth. BCC delivery, plain text | CLAUDE.md | 7 | Pending |
| KDD-ext-5 | Inbound API: POST /api/{methodName}, X-API-Key header, flat JSON, extended type system | CLAUDE.md | 7 | Pending |
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 | Pending |
| KDD-deploy-2 | Composed member addressing: [ModuleInstanceName].[MemberName] | CLAUDE.md | 2 | Pending |
| KDD-deploy-3 | Override granularity defined per entity type and per field | CLAUDE.md | 2 | Pending |
| KDD-deploy-4 | Template graph acyclicity enforced on save | CLAUDE.md | 2 | Pending |
| KDD-deploy-5 | Flattened configs include revision hash for staleness detection | CLAUDE.md | 2 | Pending |
| 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 | Pending |
| 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 | Pending |
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 | Pending |
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 | Pending |
| KDD-cluster-2 | Both nodes are seed nodes. min-nr-of-members=1 | CLAUDE.md | 3A | Pending |
| KDD-cluster-3 | Failure detection: 2s heartbeat, 10s threshold. Total failover ~25s | CLAUDE.md | 3A | Pending |
| KDD-cluster-4 | CoordinatedShutdown for graceful singleton handover | CLAUDE.md | 3A | Pending |
| KDD-cluster-5 | Automatic dual-node recovery from persistent storage | CLAUDE.md | 3A | Pending |
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 | Pending |
| KDD-ui-3 | Health reports: 30s interval, 60s offline threshold, monotonic sequence numbers, raw error counts | CLAUDE.md | 3B | Pending |
| KDD-ui-4 | Dead letter monitoring as health metric | CLAUDE.md | 3B | Pending |
| KDD-ui-5 | Site Event Logging: 30-day retention, 1GB cap, daily purge, paginated queries with keyword search | CLAUDE.md | 3B | Pending |
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 | Pending |
| KDD-code-2 | Repository interfaces in Commons; implementations in Configuration Database | CLAUDE.md | 0, 1 | Pending |
| KDD-code-3 | Commons namespace hierarchy: Types/, Interfaces/, Entities/, Messages/ with domain area subfolders | CLAUDE.md | 0 | Pending |
| KDD-code-4 | Message contracts follow additive-only evolution rules | CLAUDE.md | 0 | Pending |
| KDD-code-5 | Per-component configuration via appsettings.json sections bound to options classes | CLAUDE.md | 0, 1 | Pending |
| KDD-code-6 | Options classes owned by component projects, not Commons | CLAUDE.md | 0 | Pending |
| 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 | Pending |
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 | Pending |
| CD-DCL-2 | LmxProxy: API key auth, session-based (SessionId), 30s keep-alive heartbeat | Component-DCL | 3B | Pending |
| CD-DCL-3 | LmxProxy: Server-streaming gRPC for subscriptions, 1000ms default sampling | Component-DCL | 3B | Pending |
| CD-DCL-4 | LmxProxy: SDK retry policy (exponential backoff) complements DCL's fixed-interval reconnect | Component-DCL | 3B | Pending |
| CD-DCL-5 | LmxProxy: Batch read/write capabilities (ReadBatchAsync, WriteBatchAsync) | Component-DCL | 3B | Pending |
| CD-DCL-6 | LmxProxy: TLS 1.2/1.3, mutual TLS, self-signed for dev | Component-DCL | 3B | Pending |
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 (site failover mechanics), 8 (full-system validation) | Not yet |
| 1.4 | Deployment Behavior | 3C (pipeline), 6 (UI) | Not yet |
| 1.5 | System-Wide Artifact Deployment | 3C (backend), 6 (UI) | Not yet |
| 3.3 | Data Connections | 2 (model/binding), 3B (runtime) | Not yet |
| 3.8.1 | Instance Lifecycle | 3C (backend), 4 (UI) | Not yet |
| 3.9 | Deployment & Change Propagation | 3C (pipeline), 6 (UI) | Not yet |
| 3.10 | Areas | 2 (model), 4 (UI) | Not yet |
| 4.1 | Script Definitions | 2 (model), 3B (runtime) | Not yet |
| 4.4 | Script Capabilities | 3B (core: read/write/call), 7 (external/notify/DB) | Not yet |
| 5.1 | External System Definitions | 5 (UI), 7 (runtime) | Not yet |
| 5.3 | S&F for External Calls | 3C (engine), 7 (integration) | Not yet |
| 5.4 | Parked Message Management | 3C (backend), 6 (UI) | Not yet |
| 5.5 | Database Connections | 5 (UI), 7 (runtime) | Not yet |
| 6.1 | Notification Lists | 5 (UI), 7 (runtime) | Not yet |
| 7.4 | API Method Definitions | 5 (UI), 7 (runtime) | Not yet |
| 8 | Central UI | 4, 5, 6 (split by workflow type) | Not yet |
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. 0 bullet-level verified (verified when phase plans are generated).
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.