thephoenix08/musimo

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.