Initial commit

2026-05-06 17:56:38 +02:00
commit 8f4df1451e
78 changed files with 12130 additions and 0 deletions
@@ -0,0 +1,49 @@
+# Contributing to Bach to Basics
+
+Thanks for your interest! This guide covers the practical bits of working on the codebase.
+
+## Quick start (development)
+
+```bash
+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 --filter frontend exec tsc --noEmit`: type check
+2. `pnpm test`: frontend unit tests
+3. If you touched the backend: `cd backend && python -m py_compile $(find . -name "*.py" -not -path "./.venv/*")`
+4. 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.