[META] Option B - Complete architectural refactoring tracking

[danieljsinclair]

Issue

[Option B] Complete architectural refactoring - IAudioStrategy + IAudioHardwareProvider

Overview

This issue tracks the complete Option B architectural refactoring work to consolidate the audio layer from 10+ classes to 2 interfaces + 4 implementations.

Goal

Simplify architecture by:

• Consolidating IAudioMode + IAudioRenderer into IAudioStrategy
• Creating IAudioHardwareProvider for platform abstraction
• Reducing complexity and improving SOLID compliance
• Maintaining all existing functionality (no behavioral changes)

Architecture Transformation

Before (Current)

IAudioMode (interface)
├── ThreadedAudioMode + ThreadedRenderer (coupled pair)
└── SyncPullAudioMode + SyncPullRenderer (coupled pair)

AudioPlayer (platform-specific, uses AudioUnit directly)

After (Target)

IAudioStrategy (interface)
├── ThreadedStrategy (unified lifecycle + rendering)
└── SyncPullStrategy (unified lifecycle + rendering)

IAudioHardwareProvider (interface)
└── CoreAudioHardwareProvider (macOS implementation)
    └── AVAudioHardwareProvider (iOS, future)
    └── I2SHardwareProvider (ESP32, future)

Implementation Phases

Phase 1: Interface Design (Week 1)

• CRITICAL: Documentation describes non-existent NEW architecture (IAudioStrategy) #8: Create IAudioStrategy interface
• Remove/accurately document SilentRenderer in architecture docs #9: Create IAudioHardwareProvider interface

Phase 2: Implementation (Week 2)

• Clarify FillSilence location in architecture documentation #10: Consolidate ThreadedStrategy implementation
• Document actual pull model architecture (modes/renderers/factories) #11: Consolidate SyncPullStrategy implementation
• DECISION NEEDED: Choose architecture direction - Pull model vs NEW architecture #12: Create CoreAudioHardwareProvider implementation

Phase 3: Factory and Wiring (Week 3)

• Update QUICK_START.md to reflect current architecture #13: Create AudioStrategyFactory
• Archive and reference historical investigation docs #14: Update SimulationLoop to IAudioStrategy
• Update TELEMETRY_ARCHITECTURE.md with Reader/Writer interface split #15: Update CLIMain wiring for IAudioStrategy

Success Criteria

Architectural

• ✅ 10+ classes reduced to 2 interfaces + 4 implementations
• ✅ Clean separation of concerns (SRP)
• ✅ Open/closed principle (OCP) - new platforms easy to add
• ✅ Platform abstraction via IAudioHardwareProvider
• ✅ No coupling between mode and renderer

Testing

• ✅ All unit tests pass (GREEN)
• ✅ All smoke tests pass
• ✅ All simulator-level audio tests produce identical output
• ✅ No behavioral changes (audio sounds identical)
• ✅ Clean build with no warnings

Documentation

• ✅ Architecture documentation updated
• ✅ README updated if needed
• ✅ Code comments clear and accurate

Critical Requirements

Tests must remain GREEN throughout implementation:

• No skipping tests
• No TODO workarounds
• All existing tests must pass
• New tests for new components

Clear acceptance criteria for each issue:

• Specific, measurable, testable
• No ambiguity
• Pass/fail clear

No endless deliberation:

• Work through tickets sequentially
• Each ticket has clear acceptance criteria
• Proceed to next ticket when current is complete

Current Status

Phase 1: Interface Design - Ready to start

• ✅ Issues created with clear acceptance criteria
• ⏳ Waiting for implementation to begin

Phase 2: Implementation - Pending

• ⏳ Waiting for Phase 1 completion

Phase 3: Factory and Wiring - Pending

• ⏳ Waiting for Phase 2 completion

Dependencies

• doc-audit approval for architecture design
• solution-architect-design approval for interface design
• test-assessment verification of test coverage

References

• ARCHITECTURE_TODO.md: Current architecture documentation
• Team-lead directive: "Option B confirmed: IAudioStrategy + IAudioHardwareProvider"
• Task #82: Create GitHub tickets for Option B implementation

Notes

This refactoring is the result of comprehensive architecture audit (Task #70). The audit found CLI architecture is healthy but the audio layer has unnecessary complexity from coupled IAudioMode + IAudioRenderer pairs.

The new architecture:

• Supports cross-platform (macOS, iOS, ESP32) via IAudioHardwareProvider
• Simplifies audio strategies into single cohesive classes
• Maintains all existing functionality
• Improves SOLID compliance
• Reduces code duplication