Layer 01
Public surface
createFFTEngine(), real-input FFT APIs, CPU shortcuts, and utilities define the supported contract.
Architecture Overview
Read this page as a system note, not as marketing copy. It explains where the GPU path begins, where the CPU path remains authoritative, and why the current design stays deliberately narrow.
Architectural thesis: keep the FFT core GPU-capable, keep the public contract explicit, and keep application-level helpers honest about still being CPU-only.
System map
Read the stack from public API down to GPU passes
The project is intentionally narrow. Public APIs define the FFT contract, the execution layer owns planning and resources, GPU passes handle the transform core, and application utilities stay on CPU.
Layer 02
Execution planner
FFTEngine owns validation, execution-plan caching, buffer lifetime, and dispatch sequencing.
Layer 03
GPU compute passes
Bit reversal, butterfly stages, and scaling passes form the WebGPU FFT path.
Layer 04
CPU-only utilities
Spectrum analysis and image filtering stay on the CPU path and should never be described as GPU-native.
BoundaryGPU core and CPU-only utilities must stay explicit across docs, README, and specs.
Reading tipUnderstand the capability boundary first, then the pipeline, and the rest of the architecture reads cleanly.
Capability boundary
| Surface | Backend reality | Why it matters |
|---|---|---|
createFFTEngine() | WebGPU-backed FFT execution core | This is the primary acceleration path |
cpuFFT() / cpuIFFT() | CPU reference path | Enables universal fallback and utility reuse |
rfft() / irfft() | Shared contract across GPU and CPU paths | Makes real-input usage explicit |
createSpectrumAnalyzer() | CPU-only helper | Should never be described as GPU-native |
createImageFilter() | CPU-only helper | Uses CPU 2D FFT internally |
Execution sequence
- Validate the contract: size, shape, and real-input constraints are checked before work starts.
- Select or reuse an execution plan: the engine reuses prepared resources for previously-seen sizes instead of rebuilding everything every call.
- Dispatch GPU passes: the WebGPU path runs bit-reversal, butterfly, and scaling passes over WGSL shaders.
- Return or reconstruct output: complex or real-output contracts are restored from the transform result.
- Keep utilities honest: spectrum analysis and image filtering continue to compose CPU FFT building blocks.
Design choices that carry most of the weight
| Decision | Why it exists | Consequence |
|---|---|---|
| Radix-2 Cooley-Tukey DIT | Best fit for predictable GPU memory access and maintainable code | Input sizes must remain powers of two |
| Row-column decomposition for 2D FFT | Reuses 1D kernels instead of building a separate 2D butterfly system | Adds an explicit transpose-oriented mental model |
workgroupSize = 256 | Keeps the shader surface stable during closeout | Tuning is hardware-dependent and intentionally not over-exposed |
| Optional bank-conflict optimization | Leaves room for hardware-specific wins without changing the default contract | Default stays conservative until profiling justifies flipping it |
Shader source of truth in src/shaders/sources.ts | Avoids drift between implementation and reference copies | WGSL changes stay centralized |
Codebase map
| Layer | Files | Responsibility |
|---|---|---|
| Public API | src/index.ts, src/types.ts | Exports the supported contract |
| Core engine | src/core/fft-engine.ts, src/core/gpu-fft-backend.ts | Validation, resource lifetime, plan reuse |
| Shader truth | src/shaders/sources.ts | Canonical WGSL source strings |
| CPU utilities | src/utils/**, src/apps/** | Fallback path plus CPU-only helpers |
| Architecture notes | docs/architecture/rfc/** | Historical design context retained as normal documentation |
Read these architecture notes next
What this architecture intentionally does not do
- It does not claim GPU-native spectrum analysis.
- It does not claim GPU-native image filtering.
- It does not chase arbitrary-size FFT support in the current product slice.
- It does not optimize for every GPU family at the cost of a larger maintenance surface.