Document actual pull model architecture (modes/renderers/factories)

[danieljsinclair]

Issue Type

Documentation Update

Severity

High - Core architecture not documented

Problem Statement

The actual "pull model" architecture implemented in Feb 2026 (commit cec0a18) is not well-documented. Documentation describes a non-existent "NEW architecture" but the codebase uses a different architecture that needs proper documentation.

Current Architecture (Pull Model)

The codebase actually uses this architecture:

src/audio/
├── modes/
│   ├── IAudioMode.h           # Mode interface
│   ├── SyncPullMode.cpp/h     # Sync-pull mode implementation
│   └── ThreadedMode.cpp/h     # Threaded mode implementation
├── renderers/
│   ├── IAudioRenderer.h       # Renderer interface
│   ├── SyncPullRenderer.cpp/h # Sync-pull renderer
│   └── ThreadedRenderer.cpp/h # Threaded renderer
├── factories/
│   ├── AudioModeFactory.cpp/h # Creates mode instances
│   └── AudioRendererFactory.cpp/h # Creates renderer instances
└── utils/
    └── AudioUtils.cpp/h        # Platform-specific utilities

Architecture Pattern

• Separation of concerns: Modes (configuration/state) vs Renderers (audio generation)
• Factory pattern: Centralized creation of modes and renderers
• Strategy pattern: Different rendering strategies (sync-pull, threaded)
• Pull model: AudioPlayer pulls from renderer rather than renderer pushing

Missing Documentation

1. Architecture diagram: Visual representation of pull model
2. Component responsibilities: Clear description of each component's role
3. Interaction patterns: How modes, renderers, and factories interact
4. State management: Where state lives and how it flows
5. Threading model: Threaded mode operation details
6. Configuration: How modes are selected and configured

Acceptance Criteria

• Architecture diagram showing pull model structure
• Component responsibility documentation for each major component
• Interaction patterns documented (sequence diagrams or flow descriptions)
• Threading model clearly explained (when threads are used, synchronization)
• Configuration documentation (how to select modes, configure parameters)
• Migration guide (if applicable) from old architecture to pull model
• Code examples showing typical usage patterns

Related Issues

• CRITICAL: Documentation describes non-existent NEW architecture (IAudioStrategy) #8 - CRITICAL: Documentation describes non-existent NEW architecture

References

• Pull model implementation commit: cec0a18
• Current codebase: src/audio/modes/, src/audio/renderers/, src/audio/factories/
• Git log Feb-Apr 2026 showing pull model implementation

Note

This issue should be addressed AFTER #8 is resolved to avoid documenting incorrect architecture. Wait until we've decided whether to keep pull model or implement the NEW architecture before creating comprehensive documentation.