---

name: dsp-architecture description: DSP development patterns for this VST3 plugin. Use when working on audio processing, dsp/ folder, processors, effects, delay algorithms, filters, or any code that runs on the audio thread. Covers real-time safety, layered architecture, interpolation choices, and performance budgets. allowed-tools: Read, Grep, Glob, Bash

DSP Architecture Guide

This skill provides guidance for DSP development in this VST3 plugin project.

Quick Reference

• Real-time safety rules: See REALTIME-SAFETY.md
• Layer architecture & files: See LAYERS.md
• Implementation rules & performance: See IMPLEMENTATION.md

---

Layered Architecture Overview

Copy┌─────────────────────────────────────────────────────────────┐
│                    LAYER 4: USER FEATURES                   │
│            (Complete delay modes, full effects)             │
├─────────────────────────────────────────────────────────────┤
│                  LAYER 3: SYSTEM COMPONENTS                 │
│         (Composed processors, modulation systems)           │
├─────────────────────────────────────────────────────────────┤
│                   LAYER 2: DSP PROCESSORS                   │
│            (Filters, saturators, diffusers)                 │
├─────────────────────────────────────────────────────────────┤
│                  LAYER 1: DSP PRIMITIVES                    │
│         (Delay lines, oscillators, envelopes)               │
├─────────────────────────────────────────────────────────────┤
│                    LAYER 0: CORE UTILITIES                  │
│           (Math, conversions, buffer helpers)               │
└─────────────────────────────────────────────────────────────┘

Dependency Rules

• Each layer can ONLY depend on layers below it
• No circular dependencies
• Extract utilities to Layer 0 if used by 2+ Layer 1 primitives

Layer Include Matrix

---

Critical Rules Summary

Real-Time Thread Safety

The audio thread (Processor::process()) has hard real-time constraints.

FORBIDDEN on audio thread:

Copynew / delete / malloc / free          // Memory allocation
std::vector::push_back()              // May reallocate
std::mutex / std::lock_guard          // Blocking synchronization
throw / catch                         // Exception handling
std::cout / printf / logging          // I/O operations

See REALTIME-SAFETY.md for safe alternatives.

ODR Prevention (CRITICAL)

Before creating ANY new class/struct, search codebase:

Copygrep -r "class ClassName" dsp/ plugins/

Two classes with same name in same namespace = undefined behavior (garbage values, mysterious test failures). Check dsp_utils.h and specs/_architecture_/ before adding components.

---

Performance Budgets

---

DSP Implementation Quick Reference

See IMPLEMENTATION.md for detailed guidance.

---

File Organization

Copydsp/                              # Shared KrateDSP library (Krate::DSP namespace)
├── include/krate/dsp/
│   ├── core/                     # Layer 0 - math, conversions, utilities
│   ├── primitives/               # Layer 1 - delay lines, oscillators, envelopes
│   ├── processors/               # Layer 2 - filters, saturators, diffusers
│   ├── systems/                  # Layer 3 - composed processors, mod systems
│   └── effects/                  # Layer 4 - complete delay modes
└── tests/                        # DSP unit tests (mirrors structure above)

Include patterns:

Copy#include <krate/dsp/core/math_utils.h>
#include <krate/dsp/primitives/delay_line.h>
#include <krate/dsp/processors/biquad_filter.h>