ITOSMPiano-BachToBasics/CONTRIBUTING.md

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

1. pnpm lint: ESLint (must pass with zero warnings)
2. pnpm --filter frontend exec tsc --noEmit: type check
3. pnpm test: frontend unit tests
4. If you touched the backend: cd backend && python -m py_compile $(find . -name "*.py" -not -path "./.venv/*")
5. Verify the dev server still boots cleanly (pnpm dev)

The pre-commit hook runs ESLint + Prettier automatically on staged files, so formatting is handled for you.

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. See SECURITY.md for how to report it privately.