ONLINE
PEDALBOARD

PROJECT OVERVIEW

Modern guitarists widely adopt Impulse Responses for cabinet simulation, yet there is no seamless way to audition them without first downloading files and loading them into a DAW or hardware pedalboard. Online Pedalboard eliminates that friction by running a live signal chain directly in the browser alongside a shared community IR library.

What the application does

• Captures guitar signal via the browser's audio input APIs (getUserMedia).
• Processes the signal through a fully in-browser DSP chain: Distortion → EQ → Cabinet IR → Delay → Plate Reverb.
• Users can upload .wav IR files or choose from the shared library.
• Accounts enable saving favourites and tracking per-IR usage statistics.
• Password-reset emails are dispatched via Resend.

Tech stack at a glance

SYSTEM ARCHITECTURE

The project follows a strict client/server split. The frontend is a purely static SPA that handles all real-time audio processing client-side. The backend is stateless at the application layer — all state lives in PostgreSQL and MinIO — and is the sole authority for authentication and IR storage.

Repository structure

online-pedalboard/
├── frontend/                   # Vue 3 SPA → Vercel
│   └── src/
│       ├── PedalBoard.vue      # root orchestrator
│       ├── views/              # route-level views
│       ├── components/
│       │   ├── CabinetPedal.vue   # IR loader & convolver UI
│       │   ├── EffectPedal.vue    # delay / reverb UI
│       │   └── PreampPedal.vue   # distortion & EQ UI
│       ├── composables/
│       │   ├── useAudioEngine.js  # ← Web Audio API core
│       │   └── useIRLibrary.js    # ← IR fetch & state
│       └── router/index.js
│
└── backend/                    # FastAPI → VPS (Docker)
    ├── app/
    │   ├── main.py             # app factory & middleware
    │   ├── config.py           # Pydantic settings
    │   ├── database.py         # SQLAlchemy engine
    │   ├── dependencies.py     # auth dependency injection
    │   ├── models/             # ORM models
    │   └── routers/
    │       ├── auth.py         # /auth endpoints
    │       └── irs.py          # /irs endpoints
    ├── nginx/nginx.conf
    ├── Dockerfile
    ├── docker-compose.yml
    └── tests/

Frontend architecture

The frontend is a Vue 3 SPA built with Vite. All audio processing runs client-side; the server is never in the audio path. Two composables carry the core logic:

• useAudioEngine.js — owns the Web Audio API context, constructs the audio node graph, exposes reactive controls for each effect, and manages microphone capture.
• useIRLibrary.js — handles all REST communication: fetching the IR list, uploading new IRs, toggling favourites, and providing reactive state for the selected IR.

Backend architecture

FastAPI runs under Uvicorn, containerised with Docker. Four layers:

• Routers — thin HTTP layer: validate inputs, call service logic, return JSON responses.
• Models — SQLAlchemy ORM for Users, IRs, Favourites, and UsageTracking.
• Dependencies — FastAPI DI for the current authenticated user, verified from the JWT Bearer token.
• Object storage — MinIO stores raw .wav files. The backend uploads on POST /irs/ and returns a URL for the frontend to stream directly.

AUDIO ENGINE

The audio engine runs entirely in the browser using the Web Audio API. The design goal is the minimum achievable latency while keeping the main (UI) thread free of audio computation.

AudioWorklets

Standard ScriptProcessorNode runs on the main thread and is deprecated. The pedalboard uses AudioWorklets, which execute in a dedicated audio rendering thread. This eliminates garbage-collection pauses and UI jank that would otherwise cause audible dropouts.

Signal chain

Audio flows through the following ordered nodes. Each stage is independently bypassable via a toggle in the UI:

IR loading flow

1. User selects an IR from the library (useIRLibrary provides metadata including the .wav URL).
2. CabinetPedal calls fetch() on the presigned MinIO URL to retrieve the raw ArrayBuffer.
3. AudioContext.decodeAudioData(arrayBuffer) decodes the .wav into an AudioBuffer on the audio thread.
4. ConvolverNode.buffer is set to the decoded AudioBuffer — old convolution is replaced immediately.
5. A bypass GainNode is set to 0 during the brief decode window, then restored to 1 to avoid audible glitches.

Latency breakdown

API REFERENCE

The backend exposes a JSON REST API via FastAPI, served through Nginx at /api/*. Authentication uses JWT Bearer tokens issued by POST /auth/login and signed with HS256.

Authentication endpoints

Router: backend/app/routers/auth.py

IR library endpoints

Router: backend/app/routers/irs.py

DATABASE SCHEMA

PostgreSQL is used as the primary data store. The schema consists of four tables managed via SQLAlchemy ORM models in backend/app/models/. All primary keys are auto-incrementing integers; timestamps are stored as UTC.

Relationships

Notes

• The (user_id, ir_id) pair in favourites has a unique constraint — toggling a favourite either inserts or deletes the row.
• Passwords are hashed with bcrypt before storage; plaintext passwords are never persisted.
• The reset_token on users is a short-lived signed token; reset_token_expires is checked server-side before allowing a password change.
• storage_key on impulse_responses is the MinIO object key, not a public URL. The URL is constructed at runtime from MINIO_PUBLIC_URL + storage_key.
• download_count is a denormalised counter incremented on each file fetch for fast reads. The full event log lives in usage_events for analytics queries.

TESTING

Both the frontend and backend have independent test suites that run automatically on every push via GitHub Actions. All tests must pass before a deployment to main is triggered.

Backend — pytest

Located in backend/tests/. The suite runs against a live ephemeral PostgreSQL instance spun up as a GitHub Actions service container, ensuring tests exercise real database behaviour rather than mocks.

cd backend
pytest           # Uses a dummy sqlLite instance for testing

Frontend — Vitest

Located in frontend/src/components/__tests__/ and frontend/src/composables/__tests__/. Tests run in a jsdom environment and use Vue Test Utils to mount components in isolation.

cd frontend
npx test            # run once

Lint checks

Linting runs on every push to any branch — not just main — so code quality is enforced before a PR is even opened.

DEPLOYMENT & CI/CD

Infrastructure

Two hosting environments, four Docker containers:

Backend CI/CD pipeline

Triggered on every push. Deploy steps run only on main.

Frontend CI/CD pipeline

Required GitHub Secrets

LOCAL SETUP

Prerequisites

• Node.js 18+
• Python 3.12
• Docker and Docker Compose

Frontend

cd frontend
npm install
cp .env.example .env   # set VITE_API_URL=http://localhost:8000
npm run dev            # → http://localhost:5173

If VITE_API_URL is not set, the SPA falls back to http://localhost:8000 automatically.

Backend — local Python (recommended for dev)

Run only PostgreSQL and MinIO in Docker; run FastAPI directly for fast hot-reload iteration:

cd backend
python3.12 -m venv venv
# Windows:  .\venv\Scripts\activate
# macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Backend — full Docker Compose

cd backend
cp .env.example .env   # fill in all required values
docker compose up -d   # starts all 4 containers

Environment variables (backend)

Running tests

cd backend
pip install -r requirements.txt
pytest tests/   # requires a running PostgreSQL instance

cd frontend
npm run test    # runs Vitest

CONTRIBUTING

1. Open an issue first before submitting a PR for anything beyond small bug fixes — discuss the approach first.
2. Fork the repository and create a feature branch from main.
3. Ensure linting passes: run eslint (frontend) and ruff check (backend) locally.
4. Write or update tests for any changed behaviour.
5. Open a pull request against main with a clear description of what changed and why.

Code quality tools

• Frontend: ESLint with the Vue 3 recommended ruleset.
• Backend: Ruff — checks for unused variables, imports, and common anti-patterns.
• CI will reject PRs that fail linting or tests on any branch.

Known limitations

• Browser audio latency — inherent to the Web Audio API; AudioWorklets minimise it but cannot eliminate it.