DECISION NEEDED: Choose architecture direction - Pull model vs NEW architecture

[danieljsinclair]

Issue Type

Architecture Decision

Severity

Critical - Blocks all other documentation work

Problem Statement

We have a critical documentation-reality gap that requires a strategic decision:

Current State

• Documentation: Claims Phase 6 "COMPLETED" with NEW architecture (IAudioStrategy, IAudioHardwareProvider, strategies/, hardware/)
• Codebase: Uses pull model architecture (modes/, renderers/, factories/) implemented in Feb 2026
• Gap: Documentation describes architecture that doesn't exist

Decision Made

OPTION 2: Implement NEW Architecture (As Documented) ✅

Chosen Path: IAudioStrategy + IAudioHardwareProvider

Rationale:

• Matches documented Phase 6 vision
• Better separation of concerns (strategies + hardware providers)
• Better abstraction for future platform support (iOS, ESP32)
• Solves identified SRP violations (AudioPlayer has 28 responsibilities)
• Eliminates circular dependencies
• Enables true mix-and-match of strategies
• Makes testing easier

Implementation Plan:

• Complete simplification: 10+ classes → 2 interfaces + 4 implementations
• Clear acceptance criteria for each ticket
• Work through tickets systematically
• Tests remain GREEN (no skipping)

Next Steps

1. Create GitHub tickets with clear acceptance criteria
2. Work through tickets (no endless deliberation)
3. Tests remain GREEN (no skipping)

Critical Requirements

• Clear, unambiguous acceptance criteria
• doc-audit approval before proceeding
• Work through tickets, not fall into trap of swaying

Acceptance Criteria

• Architecture direction clearly decided and communicated
• Documentation plan established based on decision
• Development roadmap updated if needed

Related Issues

• CRITICAL: Documentation describes non-existent NEW architecture (IAudioStrategy) #8 - CRITICAL: Documentation describes non-existent NEW architecture
• Document actual pull model architecture (modes/renderers/factories) #11 - Document actual pull model architecture

Blocking

Blocks #11 (pull model documentation) - need to know if we're documenting this architecture or replacing it

References

• Architecture audit findings (Task #76)
• Git log showing pull model implementation (commit cec0a18)
• Phase 6 documentation in AUDIO_MODULE_ARCHITECTURE.md

[danieljsinclair]

Decision made: Option 2 - Implement NEW Architecture (IAudioStrategy + IAudioHardwareProvider). Proceeding with implementation tickets.