# Dawdlehorn - Architecture & Patterns

## Technical Architecture Plan

### Core Technology Stack

#### Audio Processing
- **Web Audio API**: Native browser audio processing
- **Audio Worklets**: For low-latency, real-time audio processing
- **Tone.js**: High-level audio synthesis and effects library
  - Provides instruments, effects, and scheduling
  - Built on Web Audio API with better abstractions
  - Excellent for groovebox-style synthesis

#### Input Handling
- **Web Gamepad API**: Native gamepad support
- **Custom Input Manager**: Abstraction layer for different controller types
- **Event-driven architecture**: Responsive input handling

#### UI Framework
- **Vanilla JavaScript + Web Components**: For maximum performance
- **Alternative**: Svelte (minimal runtime overhead)
- **Canvas API**: For real-time visualizations and waveforms

#### State Management
- **Custom State Manager**: Lightweight, audio-focused
- **Immutable updates**: Prevent audio glitches from state changes
- **Separate audio and UI state**: Different update cycles

### Application Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Input Layer   │    │   Audio Engine  │    │   UI Layer      │
│                 │    │                 │    │                 │
│ • Gamepad API   │───▶│ • Tone.js       │───▶│ • Web Components│
│ • MIDI API      │    │ • Audio Worklets│    │ • Canvas        │
│ • Input Manager │    │ • Synthesis     │    │ • Visualizers   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  State Manager  │
                    │                 │
                    │ • Pattern Data  │
                    │ • Audio Params  │
                    │ • UI State      │
                    └─────────────────┘
```

### Key Design Patterns

#### 1. Audio-First Architecture
- Audio processing runs in separate thread (Audio Worklets)
- UI updates never block audio processing
- State changes are batched and scheduled

#### 2. Component-Based UI
- Modular components for different controls
- Each component handles its own gamepad mappings
- Reusable across different views/modes

#### 3. Event-Driven Input
- Gamepad events trigger audio parameter changes
- Debounced input for smooth parameter transitions
- Configurable input mappings

#### 4. Pattern-Based Sequencing
- Step sequencer with pattern storage
- Real-time pattern switching
- Quantized timing for musical accuracy

### Library Selection Rationale

#### Tone.js Benefits
- Mature Web Audio abstraction
- Built-in instruments and effects
- Transport and timing utilities
- Active community and documentation

#### Web Components Benefits
- Native browser support
- Encapsulated styling and behavior
- Framework-agnostic
- Excellent for audio UI controls

#### Audio Worklets Benefits
- True real-time audio processing
- Separate thread from main UI
- Low-latency parameter updates
- Future-proof Web Audio approach

### Performance Considerations

#### Audio Performance
- Use Audio Worklets for synthesis
- Minimize garbage collection in audio thread
- Pre-allocate audio buffers
- Batch parameter updates

#### Input Performance
- Poll gamepad at 60fps
- Debounce rapid input changes
- Use requestAnimationFrame for smooth updates

#### UI Performance
- Canvas for real-time visualizations
- Virtual scrolling for large pattern lists
- Efficient DOM updates with Web Components