How jackdsnyder/singthesizer works
1. Overall shape
- This is a two-tier application: a Django backend in backend/ and a React + TypeScript frontend in frontend/.
- The product appears to be a music-focused tool for projects, tracks, audio recording, and pitch/note analysis.
2. Backend platform boundary
- The backend is a standard Django project (manage.py, singthesizer_backend/) with two app domains: users and music.
- The backend exposes API endpoints through app-specific urls.py files, with models persisted through Django ORM migrations.
3. Core music domain
- The music app is the main business subsystem.
- Its models and migrations show a Project concept with musical metadata such as BPM, key, and bars.
- This suggests the backend stores composition/session metadata rather than just raw audio blobs.
4. Music analysis pipeline
- The music/services/ package contains the computational core:
- audio_io.py for ingesting/normalizing audio data
- pitch_detection.py for extracting pitch information
- pitch_smooth.py for cleaning noisy pitch contours
- quantization.py for timing alignment
- note_events.py for converting analysis into discrete note events
- keys_scales.py for musical key/scale logic
- pipeline.py to orchestrate the full analysis flow
- This is the key backend processing boundary: raw audio in, analyzed musical structure out.
5. Backend API layer
- music/views.py and music/serializers.py indicate the app exposes structured REST-style resources rather than page rendering.
- The API likely serves project CRUD plus analysis results for the frontend to consume.
- users/views.py and users/serializers.py provide the authentication/account side of the API.
6. User/account subsystem
- The users app is separate from music functionality, which keeps identity/auth concerns isolated from musical project data.
- This boundary likely supports login/registration and authenticated access to project and track endpoints.
7. Frontend application shell
- The frontend is a Vite-based React app with TypeScript, using src/main.tsx and App.tsx as the entry points.
- contexts/AuthContext.tsx and hooks/useAuth.ts show auth state is managed client-side and shared across components.
- ProtectedRoute.tsx indicates route-level access control.
8. Frontend feature areas
- The UI is split into feature components:
- components/auth/ for login/register
- components/projects/ for project list/detail/form
- components/tracks/ for recording track interactions
- components/layout/ for shared chrome such as the header
- This maps closely to the backend domain model of users, projects, and tracks.
9. Audio interaction on the client
- src/audio/tone/ contains Tone.js-related code (synthFactory.ts, playNoteEvents.ts), so the browser is responsible for synth playback / note preview.
- useNotePreview.ts likely bridges analyzed notes or user input into immediate audible feedback.
- useRecording.ts and components/tracks/RecordTrack.tsx indicate the frontend handles recording UX before sending data to the backend.
10. Frontend service boundary
- src/services/api.ts is the HTTP boundary to the backend.
- Domain-specific client services (auth.ts, projects.ts, tracks.ts, recording.ts, audioAnalysis.ts) isolate API calls from UI components.
- token.ts suggests token-based auth is stored/managed on the client and attached to requests.
11. Data flow
- Typical flow is: user authenticates → creates/selects a project → records or uploads audio/track data → frontend calls backend services → backend runs the music analysis pipeline → frontend displays project/track results and may preview notes via Tone.js.
- The main architectural split is between interactive audio/UI behavior in the browser and musical analysis + persistence in Django.
12. Testing and quality boundaries
- Backend tests are focused on the analysis pipeline and its components, with dedicated tests for pitch detection, smoothing, quantization, note events, key/scale logic, and pipeline integration.
- This suggests the most critical correctness risk is in music computation, not just CRUD/API behavior.
13. Packaging and deployment
- docker-compose.yaml indicates containerized local orchestration for the stack.
- The repo also includes standard Django ASGI/WSGI entry points, so the backend can be served in either synchronous or async deployment setups.
Main entry points: pipeline.py Analysis pipeline · api.ts API client · music Music app · urls.py API router
Components 24
Backend
Django API and music analysis services
- Django app · Main Django backend entrypoint and server config
backend/manage.py - API router · Root URL configuration that mounts app APIs
backend/singthesizer_backend/urls.py - Settings · Project settings and environment configuration
backend/singthesizer_backend/settings.py - Users app · Account and authentication domain
backend/apps/users - Auth views · User-facing API handlers
backend/apps/users/views.py - Auth serializers · Request and response shaping for user endpoints
backend/apps/users/serializers.py - Music app · Core projects, tracks, and analysis API
backend/apps/music - Project model · Persistent music project metadata such as BPM, key, and bars
backend/apps/music/models.py - Music views · Project and analysis endpoint handlers
backend/apps/music/views.py - Music serializers · Structured API representations for music resources
backend/apps/music/serializers.py - Analysis pipeline · Orchestrates audio ingestion through note extraction
backend/apps/music/services/pipeline.py - Audio I/O · Audio loading and normalization boundary
backend/apps/music/services/audio_io.py - Pitch detect · Extracts pitch contour from audio
backend/apps/music/services/pitch_detection.py - Pitch smooth · Cleans noisy pitch contours
backend/apps/music/services/pitch_smooth.py - Quantize · Aligns detected events to musical timing
backend/apps/music/services/quantization.py - Note events · Converts analysis into discrete note events
backend/apps/music/services/note_events.py - Keys & scales · Key and scale inference and mapping logic
backend/apps/music/services/keys_scales.py
Frontend
React client and browser audio UI
- React app · Vite-based TypeScript frontend entrypoint
frontend/src/main.tsx - Auth state · Shared authentication context and hooks
frontend/src/contexts/AuthContext.tsx - Protected route · Route-level access control for authenticated screens
frontend/src/components/ProtectedRoute.tsx - API client · HTTP layer and domain service wrappers
frontend/src/services/api.ts - Projects UI · Project list, detail, and form screens
frontend/src/components/projects/ProjectList.tsx - Tracks UI · Recording and track interaction screens
frontend/src/components/tracks/RecordTrack.tsx - Browser audio · Playback and note preview synthesis in the browser
frontend/src/audio/tone/index.ts
Connections 25
- Django app → API router: boots via · Django project starts from the root URL/router config
- Django app → Settings: uses · Project reads runtime settings and installed apps
- API router → Users app: mounts · Root router includes user/auth endpoints
- API router → Music app: mounts · Root router includes music endpoints
- Users app → Auth views: exposes · User app endpoint handlers
- Users app → Auth serializers: formats · User app request/response schemas
- Music app → Music views: exposes · Music API handlers
- Music app → Music serializers: formats · Music resource schemas
- Music app → Project model: persists · Music project data stored through ORM models
- Music views → Analysis pipeline: triggers · API handlers invoke analysis processing when needed
- Analysis pipeline → Audio I/O: starts with · Pipeline ingests and normalizes audio
- Analysis pipeline → Pitch detect: runs · Pipeline detects pitch content
- Analysis pipeline → Pitch smooth: cleans · Pipeline smooths pitch contours
- Analysis pipeline → Quantize: aligns · Pipeline snaps events to musical timing
- Analysis pipeline → Note events: emits · Pipeline converts analysis into note events
- Analysis pipeline → Keys & scales: interprets · Pipeline derives musical key and scale context
- React app → Auth state: shares · App wraps screens with auth context
- React app → Protected route: protects · Authenticated routing is enforced in the shell
- React app → API client: calls · UI relies on API services for backend communication
- Projects UI → API client: reads/writes · Project screens use backend project endpoints
- Tracks UI → API client: reads/writes · Track and recording screens use backend track endpoints
- Tracks UI → Browser audio: plays · Recording UI uses browser synthesis and preview audio
- Auth state → API client: authenticates · Client auth state feeds token-bearing requests
- API client → API router: requests · Frontend API calls reach the Django router
- Browser audio → Analysis pipeline: mirrors · Client-side preview reflects analyzed musical output