Contributing to Bach to Basics

Thanks for your interest! This guide covers the practical bits of working on the codebase.

Quick start (development)

pnpm install
pnpm backend:setup       # creates backend/.venv with the core deps
pnpm dev                 # starts frontend (5173) + backend (8000) concurrently

Project layout

frontend/: React 19 + Vite + TypeScript app
- src/components/: UI components, organised by feature
- src/engine/: SyncEngine, AudioEngine, MIDI clock (no React inside)
- src/store/: Zustand state
- src/views/: top-level layouts (PracticeView)
backend/: FastAPI app
- routers/: endpoint groups (transcribe, omr, youtube, export_routes, fingering)
- services/: long-running blocking work, run in dedicated executors with timeouts
shared/: TypeScript types used by the frontend (the backend has its own duplicates intentionally, keeps backend deployable independently)

Conventions

TypeScript strict mode is on. pnpm --filter frontend exec tsc --noEmit should pass cleanly.
No any without a comment explaining why.
All audio-engine work happens off the React tree. The SyncEngine is a singleton that emits events on a mitt bus; views subscribe via useEffect.
Backend services are blocking-by-default and wrapped in _run_in_*_pool() helpers with hard timeouts. Don't add long-running CPU work directly in route handlers.

Before opening a PR

pnpm --filter frontend exec tsc --noEmit: type check
pnpm test: frontend unit tests
If you touched the backend: cd backend && python -m py_compile $(find . -name "*.py" -not -path "./.venv/*")
Verify the dev server still boots cleanly (pnpm dev)

Reporting bugs

Include:

Browser + OS version
Whether you're running via pnpm dev or Docker
Steps to reproduce
Anything in the browser console (DevTools > Console) and the backend terminal

Security

Found a vulnerability? Please don't open a public issue. Reach out via the contact info on the repo owner's GitHub profile.

2.0 KiB Raw Blame History