AUDIT_GAPS

Architecture Document vs Wiki - Content Gap Analysis

This document identifies content from RAMSES_EXTRAS_ARCHITECTURE.md that is missing or insufficiently covered in the wiki pages.

Section 4: Feature System - MISSING DETAILS

4.3. Current Features - MAJOR GAPS

Missing: Detailed Sensor Control Documentation (4.3.1-4.3.6)

The architecture document has extensive Sensor Control documentation (lines 577-789) that is NOT in the wiki:

• 4.3.1. Sensor Control resolver precedence and boundaries (lines 577-608)

  • Deterministic precedence order
  • Internal baseline computation
  • Per-metric override logic
  • Fail-closed behavior for invalid entities
  • Absolute humidity handling differences
  • Framework-level nature (doesn't create entities)

• 4.3.1. Sensor Control, Absolute Humidity and Humidity Control (lines 609-623)

  • How Humidity Control uses SensorControlResolver
  • Hybrid nature of absolute humidity
  • Fail-closed behavior for missing external entities

• 4.3.2. Sensor Control and HVAC Fan Card (lines 665-695)

  • How HVAC Fan Card uses the resolver
  • Color-coded indicators for source types
  • Sensor Sources panel behavior

• 4.3.3. CO₂ Support (lines 697-710)

  • Preview-only configuration step
  • CO₂ mappings under FAN device
  • Resolver treatment of CO₂

• 4.3.4. Practical Scenarios (lines 712-736)

  • Scenario 1: Mixed hardware
  • Scenario 2: Non-representative internal sensors
  • Real-world use cases

• 4.3.5. Configuration Walkthrough (lines 738-767)

  • Step-by-step configuration guide
  • Global overview step
  • Per-device summary

• 4.3.6. Data Flow Overview (lines 769-788)

  • ASCII diagram of data flow
  • Single source of truth explanation

Current wiki coverage: Feature-Catalog.md has only 11 lines (49-59) about Sensor Control - extremely minimal.

Missing: Detailed Ramses Debugger Documentation

Architecture document lines 813-837 contain detailed Ramses Debugger information:

• Architecture: Event-driven backend with TrafficCollector
• Traffic Analyzer details
• Log Explorer details
• Packet Log Explorer details
• Unified Messages API
• WebSocket Commands
• Key Capabilities (bounded ring buffers, regex support, etc.)

Current wiki coverage: Feature-Catalog.md has only basic description (lines 61-76).

Missing: Hello World Feature Details

Architecture document lines 797-812 explain:

• Reference for keeping features small and readable
• Single source of truth via FEATURE_DEFINITION
• Framework helpers to use
• Keeping entities thin
• Avoiding parallel config structures

Current wiki coverage: Feature-Catalog.md mentions it briefly (lines 78-85).

Section 9: Frontend Architecture - MISSING DETAILS

9.1. JavaScript Card System - GAPS

Missing from Frontend-Architecture.md:

1. Theme-Adaptive Styling (lines 1578-1582)

   • CSS using HA theme variables
   • SVG assets with theme variables
   • Light/dark theme adaptation

2. Visual Editor Registration Requirements (lines 1584-1593)

   • getConfigElement() requirement
   • getStubConfig() requirement
   • customElements.define guard
   • Import editor file requirement

3. Shared Device Helper Pattern for Editors (lines 1595-1611)

   • getAvailableDevices()
   • normalizeDeviceDescriptor()
   • filterDevicesBySlugs()
   • Consistent UX pattern

9.2. Real-Time Message System - MISSING

Completely missing from wiki:

Architecture document lines 1613-1637 cover:

• JavaScript Message Listener Integration
• Auto-registration in base-card
• handle_31DA example
• Message Processing Flow diagram

Current wiki: Frontend-Architecture.md has NO coverage of this.

9.3. Translation System - GAPS

Missing details:

Architecture document lines 1639-1680 provide:

• Feature-Centric Translation Architecture (3 levels)
• Translation Loading System with Python code example
• Fallback mechanism

Current wiki: Frontend-Architecture.md has basic coverage but missing the loading system details.

9.4. Template Systems - MISSING

Completely missing from wiki:

Architecture document lines 1682-1688 cover:

• JavaScript Template System location
• Purpose (generate HTML dynamically)
• Modular template organization
• Const.py as Source of Truth

Current wiki: Frontend-Architecture.md has NO coverage of template systems.

9.5. Entity Resolution in Cards - GAPS

Missing details:

Architecture document lines 1690-1732 provide:

• getRequiredEntities() via WebSocket
• Backend entity mapping derivation
• Caching mechanism
• On-Demand Card Loading (4-step process)
• Translation Templates
• Translation System Benefits (5 points)

Current wiki: Frontend-Architecture.md has basic coverage but missing the detailed mechanics.

Section 10: Development Guide - GAPS

10.2. Development Workflow - MISSING

Completely missing from wiki:

Architecture document lines 1772-1829 provide:

• Framework-First Development (4 steps)
• Feature Development with Framework (code example)
• Framework Component Integration (5 points)
• Testing approach
• Documentation requirements

Current wiki: Development-Guide.md has basic coding standards but missing the workflow details.

Section 11: Debugging Guide - GAPS

11.2. Debug Tools - MISSING DETAILS

Missing from wiki:

Architecture document lines 1926-1954 provide:

• SimpleEntityManager Debug
• WebSocket Testing
• Message Listener Debug
• Device Enumeration Debug
• RamsesBaseCard Debug Logging (with code example)
• Debug flag explanation

Current wiki: Debugging-and-Troubleshooting.md mentions debug tools but missing the detailed examples.

11.4. Debug Configuration - GAPS

Missing details:

Architecture document lines 1982-2046 provide:

• Logging Configuration (YAML example)
• Integration Advanced Settings (debug_mode, frontend_log_level, log_level)
• Relationship to Home Assistant "Debug Logging"
• Debug Tools Summary

Current wiki: Debugging-and-Troubleshooting.md has basic debug config but missing the advanced settings details.

Summary of Critical Missing Content

HIGH PRIORITY (Must Add):

1. Sensor Control detailed documentation (4.3.1-4.3.6) - ~200 lines

   • Should go in: Feature-Catalog.md or new Sensor-Control.md page

2. Real-Time Message System (9.2) - ~25 lines

   • Should go in: Frontend-Architecture.md

3. Template Systems (9.4) - ~7 lines

   • Should go in: Frontend-Architecture.md

4. Development Workflow (10.2) - ~58 lines

   • Should go in: Development-Guide.md

MEDIUM PRIORITY (Should Add):

5. Ramses Debugger detailed architecture - ~25 lines

   • Should go in: Feature-Catalog.md or expand existing

6. Hello World best practices - ~16 lines

   • Should go in: Feature-System.md

7. Frontend card system details (theme, editor, helpers) - ~30 lines

   • Should go in: Frontend-Architecture.md

8. Debug configuration advanced settings - ~65 lines

   • Should go in: Debugging-and-Troubleshooting.md

LOW PRIORITY (Nice to Have):

9. Translation system loading details - ~15 lines
10. Entity resolution detailed mechanics - ~20 lines

Estimated Work

• Total missing content: ~450-500 lines of critical documentation
• Pages to update: 4-5 wiki pages
• New pages needed: Possibly 1 (Sensor-Control.md if we want to separate it)