# jackdsnyder/singthesizer architecture

> Architecture diagram of the GitHub repository jackdsnyder/singthesizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jackdsnyder/singthesizer
- Repository: https://github.com/jackdsnyder/singthesizer

## Overview

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: [`backend/apps/music/services/pipeline.py`](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/pipeline.py) (Analysis pipeline), [`frontend/src/services/api.ts`](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/services/api.ts) (API client), [`backend/apps/music`](https://github.com/jackdsnyder/singthesizer/tree/main/backend/apps/music) (Music app), [`backend/singthesizer_backend/urls.py`](https://github.com/jackdsnyder/singthesizer/blob/main/backend/singthesizer_backend/urls.py) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_project["Django app<br/>[manage.py]"]
  node_backend_urls["API router<br/>django routing<br/>[urls.py]"]
  node_backend_settings["Settings<br/>django config<br/>[settings.py]"]
  node_users_app["Users app<br/>auth api"]
  node_users_views["Auth views<br/>api views<br/>[views.py]"]
  node_users_serializers["Auth serializers<br/>serialization<br/>[serializers.py]"]
  node_music_app["Music app<br/>music domain"]
  node_music_models["Project model<br/>orm models<br/>[models.py]"]
  node_music_views["Music views<br/>api views<br/>[views.py]"]
  node_music_serializers["Music serializers<br/>serialization<br/>[serializers.py]"]
  node_analysis_pipeline["Analysis pipeline<br/>audio pipeline<br/>[pipeline.py]"]
  node_audio_io["Audio I/O<br/>audio ingest<br/>[audio_io.py]"]
  node_pitch_detection["Pitch detect<br/>signal processing<br/>[pitch_detection.py]"]
  node_pitch_smooth["Pitch smooth<br/>signal processing<br/>[pitch_smooth.py]"]
  node_quantization["Quantize<br/>timing align<br/>[quantization.py]"]
  node_note_events["Note events<br/>music events<br/>[note_events.py]"]
  node_keys_scales["Keys & scales<br/>music theory<br/>[keys_scales.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>web client<br/>[main.tsx]"]
  node_auth_state["Auth state<br/>client state<br/>[AuthContext.tsx]"]
  node_route_guard["Protected route<br/>routing guard<br/>[ProtectedRoute.tsx]"]
  node_api_client["API client<br/>http boundary<br/>[api.ts]"]
  node_project_ui["Projects UI<br/>feature ui<br/>[ProjectList.tsx]"]
  node_track_ui["Tracks UI<br/>feature ui<br/>[RecordTrack.tsx]"]
  node_browser_audio["Browser audio<br/>tone.js<br/>[index.ts]"]
end

node_backend_project -->|"boots via"| node_backend_urls
node_backend_project -->|"uses"| node_backend_settings
node_backend_urls -->|"mounts"| node_users_app
node_backend_urls -->|"mounts"| node_music_app
node_users_app -->|"exposes"| node_users_views
node_users_app -->|"formats"| node_users_serializers
node_music_app -->|"exposes"| node_music_views
node_music_app -->|"formats"| node_music_serializers
node_music_app -->|"persists"| node_music_models
node_music_views -->|"triggers"| node_analysis_pipeline
node_analysis_pipeline -->|"starts with"| node_audio_io
node_analysis_pipeline -->|"runs"| node_pitch_detection
node_analysis_pipeline -->|"cleans"| node_pitch_smooth
node_analysis_pipeline -->|"aligns"| node_quantization
node_analysis_pipeline -->|"emits"| node_note_events
node_analysis_pipeline -->|"interprets"| node_keys_scales
node_frontend_app -->|"shares"| node_auth_state
node_frontend_app -->|"protects"| node_route_guard
node_frontend_app -->|"calls"| node_api_client
node_project_ui -->|"reads/writes"| node_api_client
node_track_ui -->|"reads/writes"| node_api_client
node_track_ui -->|"plays"| node_browser_audio
node_auth_state -->|"authenticates"| node_api_client
node_api_client -->|"requests"| node_backend_urls
node_browser_audio -.->|"mirrors"| node_analysis_pipeline

click node_backend_project "https://github.com/jackdsnyder/singthesizer/blob/main/backend/manage.py"
click node_backend_urls "https://github.com/jackdsnyder/singthesizer/blob/main/backend/singthesizer_backend/urls.py"
click node_backend_settings "https://github.com/jackdsnyder/singthesizer/blob/main/backend/singthesizer_backend/settings.py"
click node_users_app "https://github.com/jackdsnyder/singthesizer/tree/main/backend/apps/users"
click node_users_views "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/users/views.py"
click node_users_serializers "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/users/serializers.py"
click node_music_app "https://github.com/jackdsnyder/singthesizer/tree/main/backend/apps/music"
click node_music_models "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/models.py"
click node_music_views "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/views.py"
click node_music_serializers "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/serializers.py"
click node_analysis_pipeline "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/pipeline.py"
click node_audio_io "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/audio_io.py"
click node_pitch_detection "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/pitch_detection.py"
click node_pitch_smooth "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/pitch_smooth.py"
click node_quantization "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/quantization.py"
click node_note_events "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/note_events.py"
click node_keys_scales "https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/keys_scales.py"
click node_frontend_app "https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/main.tsx"
click node_auth_state "https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_route_guard "https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/components/ProtectedRoute.tsx"
click node_api_client "https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/services/api.ts"
click node_project_ui "https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/components/projects/ProjectList.tsx"
click node_track_ui "https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/components/tracks/RecordTrack.tsx"
click node_browser_audio "https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/audio/tone/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_project,node_backend_urls,node_backend_settings,node_users_app,node_users_views,node_users_serializers,node_music_app,node_music_models,node_music_views,node_music_serializers,node_analysis_pipeline,node_audio_io,node_pitch_detection,node_pitch_smooth,node_quantization,node_note_events,node_keys_scales toneBlue
class node_frontend_app,node_auth_state,node_route_guard,node_api_client,node_project_ui,node_track_ui,node_browser_audio toneAmber
```

## Components

### Backend

Django API and music analysis services

- [Django app](https://github.com/jackdsnyder/singthesizer/blob/main/backend/manage.py): project · Main Django backend entrypoint and server config · `backend/manage.py`
- [API router](https://github.com/jackdsnyder/singthesizer/blob/main/backend/singthesizer_backend/urls.py): django routing · Root URL configuration that mounts app APIs · `backend/singthesizer_backend/urls.py`
- [Settings](https://github.com/jackdsnyder/singthesizer/blob/main/backend/singthesizer_backend/settings.py): django config · Project settings and environment configuration · `backend/singthesizer_backend/settings.py`
- [Users app](https://github.com/jackdsnyder/singthesizer/tree/main/backend/apps/users): auth api · Account and authentication domain · `backend/apps/users`
- [Auth views](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/users/views.py): api views · User-facing API handlers · `backend/apps/users/views.py`
- [Auth serializers](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/users/serializers.py): serialization · Request and response shaping for user endpoints · `backend/apps/users/serializers.py`
- [Music app](https://github.com/jackdsnyder/singthesizer/tree/main/backend/apps/music): music domain · Core projects, tracks, and analysis API · `backend/apps/music`
- [Project model](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/models.py): orm models · Persistent music project metadata such as BPM, key, and bars · `backend/apps/music/models.py`
- [Music views](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/views.py): api views · Project and analysis endpoint handlers · `backend/apps/music/views.py`
- [Music serializers](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/serializers.py): serialization · Structured API representations for music resources · `backend/apps/music/serializers.py`
- [Analysis pipeline](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/pipeline.py): audio pipeline · Orchestrates audio ingestion through note extraction · `backend/apps/music/services/pipeline.py`
- [Audio I/O](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/audio_io.py): audio ingest · Audio loading and normalization boundary · `backend/apps/music/services/audio_io.py`
- [Pitch detect](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/pitch_detection.py): signal processing · Extracts pitch contour from audio · `backend/apps/music/services/pitch_detection.py`
- [Pitch smooth](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/pitch_smooth.py): signal processing · Cleans noisy pitch contours · `backend/apps/music/services/pitch_smooth.py`
- [Quantize](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/quantization.py): timing align · Aligns detected events to musical timing · `backend/apps/music/services/quantization.py`
- [Note events](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/note_events.py): music events · Converts analysis into discrete note events · `backend/apps/music/services/note_events.py`
- [Keys & scales](https://github.com/jackdsnyder/singthesizer/blob/main/backend/apps/music/services/keys_scales.py): music theory · Key and scale inference and mapping logic · `backend/apps/music/services/keys_scales.py`

### Frontend

React client and browser audio UI

- [React app](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/main.tsx): web client · Vite-based TypeScript frontend entrypoint · `frontend/src/main.tsx`
- [Auth state](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/contexts/AuthContext.tsx): client state · Shared authentication context and hooks · `frontend/src/contexts/AuthContext.tsx`
- [Protected route](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/components/ProtectedRoute.tsx): routing guard · Route-level access control for authenticated screens · `frontend/src/components/ProtectedRoute.tsx`
- [API client](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/services/api.ts): http boundary · HTTP layer and domain service wrappers · `frontend/src/services/api.ts`
- [Projects UI](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/components/projects/ProjectList.tsx): feature ui · Project list, detail, and form screens · `frontend/src/components/projects/ProjectList.tsx`
- [Tracks UI](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/components/tracks/RecordTrack.tsx): feature ui · Recording and track interaction screens · `frontend/src/components/tracks/RecordTrack.tsx`
- [Browser audio](https://github.com/jackdsnyder/singthesizer/blob/main/frontend/src/audio/tone/index.ts): tone.js · Playback and note preview synthesis in the browser · `frontend/src/audio/tone/index.ts`

## Connections

- 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
