50 lines
2.0 KiB
Markdown
50 lines
2.0 KiB
Markdown
# 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.
|