# thephoenix08/musimo architecture

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

- Interactive diagram: https://gitdiagram.com/thephoenix08/musimo
- Repository: https://github.com/thephoenix08/musimo

## Overview

#### Purpose and Entry Points
Musimo is a work-in-progress audio-analysis platform with a React/Vite client and Python backend. It supports authenticated project libraries, audio upload/playback, emotion and instrument recognition, audio-feature analysis, and source separation. Client bootstraps at `client/src/main.jsx` into `client/src/App.jsx`; the backend ASGI entry point is `server/main.py`, built through `server/src/core/app_factory.py`.

#### Client Application Shell
The frontend is a feature-oriented SPA. Global providers, Redux store, theme, routing constants, and layout selection form its application boundary:
- `client/src/shared/providers/global.provider.jsx`
- `client/src/shared/state/store/store.js`
- `client/src/shared/layouts/AppLayout.wrapper.jsx`
- `client/src/shared/constants/routes.constants.js`

Public, auth, and analysis experiences are separated by dedicated layouts, with sidebar navigation for authenticated application routes.

#### Identity, Sessions, and User Management
Authentication is implemented as a client Redux/API flow backed by server auth, OTP, token, and user services. The UI includes login, registration, password recovery/reset, and OTP forms:
- `client/src/features/auth/flows/userAuth.flow.js`
- `client/src/features/auth/state/redux-api/auth.api.js`
- `server/src/routes/auth.py`
- `server/src/services/auth_service.py`
- `server/src/services/otp_service.py`

Persistence models include users, refresh tokens, and OTP records under `server/src/database/models/`.

#### Project and Audio Lifecycle
Projects organize uploaded audio and their derived analysis records. The library UI calls project APIs and Redux state; backend routes delegate to services/repositories and database models:
- `client/src/features/library/library.page.jsx`
- `client/src/features/library/actions/project.api.js`
- `server/src/routes/project.py`
- `server/src/services/project.py`
- `server/src/repo/projectRepo.py`

Audio-file operations are a separate backend boundary, with scheduled cleanup/sweeping indicating uploaded artifacts can expire:
- `server/src/routes/audio_file.py`
- `server/src/services/audio_file.py`
- `server/src/core/audio_file_sweeper.py`
- `server/src/database/models/audio_file.py`

#### Analysis Workspace and Delivery
The analysis interface presents audio playback plus distinct views for emotion, instruments, mid-level features, separation, and job status:
- `client/src/features/interface/interface.page.jsx`
- `client/src/features/interface/audio-player/AudioPlayerFooter.jsx`
- `client/src/features/interface/api/analysis.api.js`
- `server/src/routes/analysis.py`
- `server/src/services/analysis_service.py`

The client supports both request-based and WebSocket analysis hooks. Backend WebSocket routing provides a real-time channel, likely used for progressive prediction/job results:
- `client/src/features/interface/views/emotion/hooks/useEmotionAnalysisWebsocket.js`
- `client/src/features/interface/views/instrument/hooks/useInstrumentalAnalysisWebsocket.js`
- `server/src/routes/websocket/ws_router.py`

#### ML and Audio Processing Pipelines
Model execution is isolated from HTTP routes in dedicated pipelines and workflow services. Emotion and instrument recognition each follow preprocessing/embedding/inference/postprocessing stages; workflows coordinate them with analysis persistence:
- `server/src/models/emotion_recognition/emotion_pipeline.py`
- `server/src/models/Instrument_recognition/instrument_pipeline.py`
- `server/src/services/emotion_workflow_service.py`
- `server/src/services/instrument_workflow_service.py`

Feature extraction and source separation are separate capabilities. Separation includes progress tracking, job state, stem persistence, and Celery tasks:
- `server/src/services/audio_feature_service.py`
- `server/src/routes/separate_audio.py`
- `server/src/services/stem_tasks.py`
- `server/src/services/celery_app.py`
- `server/src/models/audio_separation/pipelines/separation.py`

#### Backend Runtime, Persistence, and Integrations
The backend is a FastAPI-style ASGI service configured through lifecycle/bootstrap, middleware, settings, and route registration:
- `server/src/core/bootstrap.py`
- `server/src/core/lifespan.py`
- `server/src/core/settings.py`
- `server/src/routes/__init__.py`

Database access uses SQLAlchemy-style models, sessions, repositories, and Alembic migrations. Supabase, storage, email, Modal, and an LLM are explicit integration boundaries:
- `server/src/database/session.py`
- `server/src/database/models/analysis_record.py`
- `server/src/core/supabase.py`
- `server/src/services/storage.py`
- `server/src/services/modal_client.py`
- `server/src/services/llm_service.py`

The server is containerized via `server/Dockerfile`; local execution uses `uvicorn main:app --port 8000 --reload`.

Main entry points: [`server/src/database/session.py`](https://github.com/thephoenix08/musimo/blob/main/server/src/database/session.py) (Application database), [`server/src/core/app_factory.py`](https://github.com/thephoenix08/musimo/blob/main/server/src/core/app_factory.py) (Application factory), [`server/src/routes/analysis.py`](https://github.com/thephoenix08/musimo/blob/main/server/src/routes/analysis.py) (Analysis API), [`client/src/App.jsx`](https://github.com/thephoenix08/musimo/blob/main/client/src/App.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_client_entry["Client entry<br/>Vite bootstrap<br/>[main.jsx]"]
  node_client_shell["App shell<br/>providers, store &amp; layouts<br/>[App.jsx]"]
  node_auth_ui["Auth flows<br/>Redux API flow<br/>[userAuth.flow.js]"]
  node_library_ui["Project library<br/>library page<br/>[library.page.jsx]"]
  node_analysis_ui["Analysis workspace<br/>audio player &amp; views<br/>[interface.page.jsx]"]
  node_analysis_ws_hooks["Analysis WebSocket hooks<br/>client realtime hooks"]
end

subgraph group_backend["ASGI Backend"]
  node_asgi_entry["ASGI entry<br/>FastAPI runtime<br/>[main.py]"]
  node_app_factory["Application factory<br/>bootstrap &amp; route assembly<br/>[app_factory.py]"]
  node_auth_api["Auth API<br/>routes &amp; services<br/>[auth.py]"]
  node_project_api["Project API<br/>routes, service &amp; repository<br/>[project.py]"]
  node_audio_files["Audio file lifecycle<br/>upload service &amp; sweeper<br/>[audio_file.py]"]
  node_analysis_api["Analysis API<br/>analysis service<br/>[analysis.py]"]
  node_websocket_router["WebSocket router<br/>realtime endpoint<br/>[ws_router.py]"]
end

subgraph group_processing["Audio Processing"]
  node_recognition_workflows["Recognition workflows<br/>emotion &amp; instrument orchestration"]
  node_recognition_models["Recognition pipelines<br/>preprocess, inference &amp; postprocess"]
  node_feature_analysis["Audio feature analysis<br/>feature extraction service"]
  node_separation_jobs["Source separation jobs<br/>[stem_tasks.py]"]
end

subgraph group_platform["Persistence &amp; Integrations"]
  node_database[("Application database<br/>SQLAlchemy models &amp; sessions<br/>[session.py]")]
  node_storage[("Object storage<br/>storage integration<br/>[storage.py]")]
  node_external_services{{"External services<br/>[supabase.py]"}}
end

node_client_entry -->|"mounts"| node_client_shell
node_client_shell -->|"routes to"| node_auth_ui
node_client_shell -->|"routes to"| node_library_ui
node_client_shell -->|"routes to"| node_analysis_ui
node_analysis_ui -->|"uses"| node_analysis_ws_hooks
node_auth_ui -->|"auth requests"| node_auth_api
node_library_ui -->|"project requests"| node_project_api
node_analysis_ui -->|"analysis requests"| node_analysis_api
node_analysis_ws_hooks -->|"realtime updates"| node_websocket_router
node_asgi_entry -->|"builds"| node_app_factory
node_app_factory -->|"registers"| node_auth_api
node_app_factory -->|"registers"| node_project_api
node_app_factory -->|"registers"| node_analysis_api
node_app_factory -->|"registers"| node_websocket_router
node_project_api -->|"manages audio"| node_audio_files
node_auth_api -->|"persists identity"| node_database
node_project_api -->|"persists projects"| node_database
node_audio_files -->|"stores artifacts"| node_storage
node_audio_files -->|"tracks files"| node_database
node_analysis_api -->|"runs recognition"| node_recognition_workflows
node_analysis_api -->|"extracts features"| node_feature_analysis
node_analysis_api -->|"submits separation"| node_separation_jobs
node_recognition_workflows -->|"executes"| node_recognition_models
node_recognition_workflows -->|"persists results"| node_database
node_feature_analysis -->|"persists results"| node_database
node_separation_jobs -->|"writes stems"| node_storage
node_separation_jobs -->|"tracks job state"| node_database
node_websocket_router -.->|"reports progress"| node_separation_jobs
node_auth_api -.->|"uses integrations"| node_external_services

click node_client_entry "https://github.com/thephoenix08/musimo/blob/main/client/src/main.jsx"
click node_client_shell "https://github.com/thephoenix08/musimo/blob/main/client/src/App.jsx"
click node_auth_ui "https://github.com/thephoenix08/musimo/blob/main/client/src/features/auth/flows/userAuth.flow.js"
click node_library_ui "https://github.com/thephoenix08/musimo/blob/main/client/src/features/library/library.page.jsx"
click node_analysis_ui "https://github.com/thephoenix08/musimo/blob/main/client/src/features/interface/interface.page.jsx"
click node_analysis_ws_hooks "https://github.com/thephoenix08/musimo/blob/main/client/src/features/interface/views/emotion/hooks/useEmotionAnalysisWebsocket.js"
click node_asgi_entry "https://github.com/thephoenix08/musimo/blob/main/server/main.py"
click node_app_factory "https://github.com/thephoenix08/musimo/blob/main/server/src/core/app_factory.py"
click node_auth_api "https://github.com/thephoenix08/musimo/blob/main/server/src/routes/auth.py"
click node_project_api "https://github.com/thephoenix08/musimo/blob/main/server/src/routes/project.py"
click node_audio_files "https://github.com/thephoenix08/musimo/blob/main/server/src/services/audio_file.py"
click node_analysis_api "https://github.com/thephoenix08/musimo/blob/main/server/src/routes/analysis.py"
click node_websocket_router "https://github.com/thephoenix08/musimo/blob/main/server/src/routes/websocket/ws_router.py"
click node_recognition_workflows "https://github.com/thephoenix08/musimo/blob/main/server/src/services/emotion_workflow_service.py"
click node_recognition_models "https://github.com/thephoenix08/musimo/blob/main/server/src/models/emotion_recognition/emotion_pipeline.py"
click node_feature_analysis "https://github.com/thephoenix08/musimo/blob/main/server/src/services/audio_feature_service.py"
click node_separation_jobs "https://github.com/thephoenix08/musimo/blob/main/server/src/services/stem_tasks.py"
click node_database "https://github.com/thephoenix08/musimo/blob/main/server/src/database/session.py"
click node_storage "https://github.com/thephoenix08/musimo/blob/main/server/src/services/storage.py"
click node_external_services "https://github.com/thephoenix08/musimo/blob/main/server/src/core/supabase.py"

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_client_entry,node_client_shell,node_auth_ui,node_library_ui,node_analysis_ui,node_analysis_ws_hooks toneBlue
class node_asgi_entry,node_app_factory,node_auth_api,node_project_api,node_audio_files,node_analysis_api,node_websocket_router toneAmber
class node_recognition_workflows,node_recognition_models,node_feature_analysis,node_separation_jobs toneMint
class node_database,node_storage,node_external_services toneRose
```

## Components

### React Client

- [Client entry](https://github.com/thephoenix08/musimo/blob/main/client/src/main.jsx): Vite bootstrap · `client/src/main.jsx`
- [App shell](https://github.com/thephoenix08/musimo/blob/main/client/src/App.jsx): providers, store & layouts · Selects layouts and application routes. · `client/src/App.jsx`
- [Auth flows](https://github.com/thephoenix08/musimo/blob/main/client/src/features/auth/flows/userAuth.flow.js): Redux API flow · Login, registration, recovery, reset, and OTP UI. · `client/src/features/auth/flows/userAuth.flow.js`
- [Project library](https://github.com/thephoenix08/musimo/blob/main/client/src/features/library/library.page.jsx): library page · `client/src/features/library/library.page.jsx`
- [Analysis workspace](https://github.com/thephoenix08/musimo/blob/main/client/src/features/interface/interface.page.jsx): audio player & views · Presents emotion, instruments, features, separation, and job status. · `client/src/features/interface/interface.page.jsx`
- [Analysis WebSocket hooks](https://github.com/thephoenix08/musimo/blob/main/client/src/features/interface/views/emotion/hooks/useEmotionAnalysisWebsocket.js): client realtime hooks · `client/src/features/interface/views/emotion/hooks/useEmotionAnalysisWebsocket.js`

### ASGI Backend

- [ASGI entry](https://github.com/thephoenix08/musimo/blob/main/server/main.py): FastAPI runtime · `server/main.py`
- [Application factory](https://github.com/thephoenix08/musimo/blob/main/server/src/core/app_factory.py): bootstrap & route assembly · Builds the server application and lifecycle. · `server/src/core/app_factory.py`
- [Auth API](https://github.com/thephoenix08/musimo/blob/main/server/src/routes/auth.py): routes & services · Manages sessions, tokens, OTP, and users. · `server/src/routes/auth.py`
- [Project API](https://github.com/thephoenix08/musimo/blob/main/server/src/routes/project.py): routes, service & repository · Organizes projects and their analysis records. · `server/src/routes/project.py`
- [Audio file lifecycle](https://github.com/thephoenix08/musimo/blob/main/server/src/services/audio_file.py): upload service & sweeper · Handles uploaded artifacts and expiry cleanup. · `server/src/services/audio_file.py`
- [Analysis API](https://github.com/thephoenix08/musimo/blob/main/server/src/routes/analysis.py): analysis service · Receives analysis requests and returns persisted results. · `server/src/routes/analysis.py`
- [WebSocket router](https://github.com/thephoenix08/musimo/blob/main/server/src/routes/websocket/ws_router.py): realtime endpoint · Streams progressive analysis and job results. · `server/src/routes/websocket/ws_router.py`

### Audio Processing

- [Recognition workflows](https://github.com/thephoenix08/musimo/blob/main/server/src/services/emotion_workflow_service.py): emotion & instrument orchestration · Coordinates model runs with analysis persistence. · `server/src/services/emotion_workflow_service.py`
- [Recognition pipelines](https://github.com/thephoenix08/musimo/blob/main/server/src/models/emotion_recognition/emotion_pipeline.py): preprocess, inference & postprocess · Emotion and instrument model execution. · `server/src/models/emotion_recognition/emotion_pipeline.py`
- [Audio feature analysis](https://github.com/thephoenix08/musimo/blob/main/server/src/services/audio_feature_service.py): feature extraction service · `server/src/services/audio_feature_service.py`
- [Source separation jobs](https://github.com/thephoenix08/musimo/blob/main/server/src/services/stem_tasks.py): Celery tasks & separation pipeline · Tracks progress and persists separated stems. · `server/src/services/stem_tasks.py`

### Persistence & Integrations

- [Application database](https://github.com/thephoenix08/musimo/blob/main/server/src/database/session.py): SQLAlchemy models & sessions · Stores users, tokens, projects, files, records, jobs, and stems. · `server/src/database/session.py`
- [Object storage](https://github.com/thephoenix08/musimo/blob/main/server/src/services/storage.py): storage integration · Stores uploaded audio and generated artifacts. · `server/src/services/storage.py`
- [External services](https://github.com/thephoenix08/musimo/blob/main/server/src/core/supabase.py): Supabase, email, Modal & LLM · `server/src/core/supabase.py`

## Connections

- Client entry → App shell: mounts
- App shell → Auth flows: routes to
- App shell → Project library: routes to
- App shell → Analysis workspace: routes to
- Analysis workspace → Analysis WebSocket hooks: uses
- Auth flows → Auth API: auth requests
- Project library → Project API: project requests
- Analysis workspace → Analysis API: analysis requests
- Analysis WebSocket hooks → WebSocket router: realtime updates
- ASGI entry → Application factory: builds
- Application factory → Auth API: registers
- Application factory → Project API: registers
- Application factory → Analysis API: registers
- Application factory → WebSocket router: registers
- Project API → Audio file lifecycle: manages audio
- Auth API → Application database: persists identity
- Project API → Application database: persists projects
- Audio file lifecycle → Object storage: stores artifacts
- Audio file lifecycle → Application database: tracks files
- Analysis API → Recognition workflows: runs recognition
- Analysis API → Audio feature analysis: extracts features
- Analysis API → Source separation jobs: submits separation
- Recognition workflows → Recognition pipelines: executes
- Recognition workflows → Application database: persists results
- Audio feature analysis → Application database: persists results
- Source separation jobs → Object storage: writes stems
- Source separation jobs → Application database: tracks job state
- WebSocket router → Source separation jobs: reports progress
- Auth API → External services: uses integrations