Document LmxProxy protocol in DCL, strengthen plan generation traceability guards, and add UI constraints
- 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
This commit is contained in:
Joseph Doherty
@@ -1,6 +1,10 @@
|
||||
# Requirements Traceability Matrix
|
||||
|
||||
**Purpose**: Ensures every requirement from HighLevelReqs.md and every REQ-* identifier maps to at least one implementation phase. Updated as plan documents are generated.
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
@@ -102,9 +106,160 @@
|
||||
|
||||
---
|
||||
|
||||
## 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 have at least one phase assignment. Coverage will be re-verified as each phase plan is 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.
|
||||
|
||||
Reference in New Issue
Block a user