plugin-architecture-patterns

What this skill does

# Plugin Architecture Patterns

Master architectural patterns for building maintainable, testable, and scalable audio plugins using clean architecture, separation of concerns, and JUCE best practices.

## Overview

This skill provides comprehensive guidance on structuring JUCE audio plugins using proven architectural patterns. It covers separation of DSP from UI, state management, preset systems, parameter handling, MIDI routing, and modulation architectures.

## When to Use This Skill

- Designing a new plugin architecture from scratch
- Refactoring an existing plugin for better maintainability
- Implementing complex state management or modulation routing
- Planning multi-format plugin support (VST3/AU/AAX)
- Building plugins that need to scale (many parameters, voices, effects)

## Core Architectural Principles

### 1. Separation of Concerns

Audio plugins have distinct responsibilities that should be isolated:

```
┌─────────────────────────────────────────────────┐
│                  Plugin Host                    │
└─────────────────────┬───────────────────────────┘
                      │
          ┌───────────┴───────────┐
          │                       │
    ┌─────▼──────┐         ┌─────▼──────┐
    │ Processor  │         │   Editor   │
    │  (Audio)   │◄────────┤    (UI)    │
    └─────┬──────┘         └────────────┘
          │
    ┌─────▼──────┐
    │ DSP Engine │
    └─────┬──────┘
          │
    ┌─────▼──────┬──────────┬───────────┐
    │   Filter   │ Envelope │ Oscillator│
    └────────────┴──────────┴───────────┘
```

**Key Separations:**
- **DSP Logic** - Pure audio processing, realtime-safe
- **Parameter Management** - Value storage, automation, presets
- **UI Layer** - Rendering, user interaction (not realtime-safe)
- **State Management** - Serialization, preset loading/saving

---

## Architecture Pattern 1: Clean Architecture

### Layer Structure

```
┌──────────────────────────────────────────┐
│         Presentation Layer (UI)          │  ← JUCE Components, Graphics
├──────────────────────────────────────────┤
│      Application Layer (Processor)       │  ← AudioProcessor, parameter handling
├──────────────────────────────────────────┤
│         Domain Layer (DSP Core)          │  ← Pure audio algorithms
├──────────────────────────────────────────┤
│     Infrastructure (JUCE Framework)      │  ← JUCE modules, OS/DAW interface
└──────────────────────────────────────────┘
```

**Dependency Rule:** Outer layers depend on inner layers, never the reverse.

### Example: Clean Architecture in JUCE

```cpp
// ============================================================================
// Domain Layer - Pure DSP (no JUCE dependencies except juce::dsp)
// ============================================================================

// Source/DSP/FilterCore.h
class FilterCore {
public:
    void setFrequency(float hz, float sampleRate) {
        // Pure calculation, no allocations
        coefficients = calculateCoefficients(hz, sampleRate);
    }

    float processSample(float input) noexcept {
        // Realtime-safe processing
        return filter.processSample(input, coefficients);
    }

    void reset() noexcept {
        filter.reset();
    }

private:
    struct Coefficients { float b0, b1, b2, a1, a2; };
    Coefficients coefficients;
    BiquadFilter filter;

    static Coefficients calculateCoefficients(float hz, float sampleRate);
};

// ============================================================================
// Application Layer - Parameter Management
// ============================================================================

// Source/PluginProcessor.h
class MyPluginProcessor : public juce::AudioProcessor {
public:
    MyPluginProcessor()
        : parameters(*this, nullptr, "Parameters", createParameterLayout())
    {
        // Connect parameters to DSP
        cutoffParam = parameters.getRawParameterValue("cutoff");
    }

    void prepareToPlay(double sampleRate, int samplesPerBlock) override {
        filterCore.reset();
        currentSampleRate = sampleRate;
    }

    void processBlock(juce::AudioBuffer<float>& buffer, juce::MidiBuffer&) override {
        // Update DSP from parameters (thread-safe)
        float cutoff = cutoffParam->load();
        filterCore.setFrequency(cutoff, currentSampleRate);

        // Process audio
        for (int ch = 0; ch < buffer.getNumChannels(); ++ch) {
            auto* data = buffer.getWritePointer(ch);
            for (int i = 0; i < buffer.getNumSamples(); ++i) {
                data[i] = filterCore.processSample(data[i]);
            }
        }
    }

    void getStateInformation(juce::MemoryBlock& destData) override {
        auto state = parameters.copyState();
        std::unique_ptr<juce::XmlElement> xml(state.createXml());
        copyXmlToBinary(*xml, destData);
    }

    void setStateInformation(const void* data, int sizeInBytes) override {
        std::unique_ptr<juce::XmlElement> xml(getXmlFromBinary(data, sizeInBytes));
        if (xml && xml->hasTagName(parameters.state.getType()))
            parameters.replaceState(juce::ValueTree::fromXml(*xml));
    }

private:
    juce::AudioProcessorValueTreeState parameters;
    std::atomic<float>* cutoffParam;

    FilterCore filterCore;  // Domain layer object
    double currentSampleRate = 44100.0;

    static juce::AudioProcessorValueTreeState::ParameterLayout createParameterLayout();
};

// ============================================================================
// Presentation Layer - UI
// ============================================================================

// Source/PluginEditor.h
class MyPluginEditor : public juce::AudioProcessorEditor {
public:
    MyPluginEditor(MyPluginProcessor& p)
        : AudioProcessorEditor(&p), processor(p)
    {
        // Attach UI to parameters (APVTS handles thread-safety)
        cutoffAttachment = std::make_unique<SliderAttachment>(
            processor.getParameters(), "cutoff", cutoffSlider
        );

        addAndMakeVisible(cutoffSlider);
    }

private:
    using SliderAttachment = juce::AudioProcessorValueTreeState::SliderAttachment;

    MyPluginProcessor& processor;
    juce::Slider cutoffSlider;
    std::unique_ptr<SliderAttachment> cutoffAttachment;
};
```

**Benefits:**
- ✅ DSP is testable without JUCE (can unit test `FilterCore` standalone)
- ✅ UI changes don't affect DSP
- ✅ Easy to swap DSP implementations
- ✅ Clear separation of realtime-safe vs non-realtime code

---

## Architecture Pattern 2: Parameter-Centric Architecture

### Using AudioProcessorValueTreeState (APVTS)

JUCE's APVTS is the recommended way to manage parameters:

```cpp
// Parameters.h - Centralized parameter definitions
namespace Parameters {
    inline const juce::ParameterID cutoff { "cutoff", 1 };
    inline const juce::ParameterID resonance { "resonance", 1 };
    inline const juce::ParameterID gain { "gain", 1 };

    inline juce::AudioProcessorValueTreeState::ParameterLayout createLayout() {
        std::vector<std::unique_ptr<juce::RangedAudioParameter>> params;

        params.push_back(std::make_unique<juce::AudioParameterFloat>(
            cutoff,
            "Cutoff",
            juce::NormalisableRange<float>(20.0f, 20000.0f, 0.01f, 0.3f),  // Skew for log
            1000.0f
        ));

        params.push_back(std::make_unique<juce::AudioParameterFloat>(
            resonance,
            "Resonance",
            juce::NormalisableRange<float>(0.1f, 10.0f),
            1.0f
        ));

        params.push_back(std::make_unique<juce::AudioParameterFloat>(
            gain,
            "Gain",
            juce::NormalisableRange<float>(-24.0f, 24.0f),
            0.0f
        ));

        return { params.begin(), params.end() };
    }
}

// PluginProcessor.h
class MyPluginProcessor : public juce::AudioProcessor {
public:
    MyPluginProcessor()
        : apvts(*this, nullptr, "Parameters", Parameters::createLayout())
    {
        // Get raw parameter