# 12mv2/harmony architecture

> Architecture diagram of the GitHub repository 12mv2/harmony, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/12mv2/harmony
- Repository: https://github.com/12mv2/harmony

## Overview

##### Main System Components

a. Frontend Layer (React Application)
- Located in /src/components and /src/pages
- Components for audio recording, playback, and user authentication
- Connection to backend via API calls

b. Backend Server Layer (Node.js/Express)
- Located in /src/server
- Controllers, routes, and middleware
- Connection to both database and ML service

c. ML Service Layer (Python)
- Located in /ml_service
- OpenMusicLM model architecture
- Audio processing pipeline

##### Detailed Component Breakdown

- AudioRecorder
- AudioPlayer
- UserVoice
- Authentication pages (Login/Register)
- Studio page

- API Router
- Controllers (Audio & Auth)
- Middleware
- Database connection
- File storage system

- FastAPI service
- Model components (CLAP, HuBERT, EnCodec)
- Input/Output processors

- User interaction flow (recording → processing → playback)
- API requests between frontend and backend
- File transfers for audio processing
- Database operations
- ML service communication

##### Integration Points

Integration points with external services:
- Supabase database connection
- File storage system
- Authentication service

##### Technical Stack Indicators

Technology labels:
- Frontend: React, TypeScript, Tailwind CSS
- Backend: Node.js, Express
- ML Service: Python, FastAPI, OpenMusicLM
- Database: Supabase
- Testing: Jest

##### Specific Implementation Details

- Audio processing pipeline
- ML model architecture
- Data persistence flow
- Authentication flow

**[Client Layer]**
- ↕ HTTP/WebSocket
**[Backend Layer]**
- ↕ HTTP/REST
**[ML Service Layer]**
- ↕
**[Database/Storage Layer]**

##### Additional Elements

Include:
- Version information
- System requirements
- Key dependencies

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef frontend fill:#e1f5fe,stroke:#01579b
    classDef backend fill:#e8f5e9,stroke:#1b5e20
    classDef ml fill:#f3e5f5,stroke:#4a148c
    classDef database fill:#fff3e0,stroke:#e65100
    classDef api fill:#fce4ec,stroke:#880e4f

    %% Frontend Layer
    subgraph Frontend
        UI[User Interface]
        AR[Audio Recorder]:::frontend
        AP[Audio Player]:::frontend
        UV[User Voice]:::frontend
        Auth[Authentication]:::frontend
        Studio[Studio Interface]:::frontend
    end

    %% Backend Layer
    subgraph Backend
        APIRouter[API Router]:::backend
        AuthC[Auth Controller]:::backend
        AudioC[Audio Controller]:::backend
        FileHandler[File Upload Handler]:::backend
        DBConn[Database Connection]:::backend
        Storage[File Storage System]:::backend
    end

    %% ML Service Layer
    subgraph MLService
        MLAPI[FastAPI Service]:::ml
        subgraph ModelComponents
            CLAP[CLAP Model]:::ml
            HuBERT[HuBERT]:::ml
            EnCodec[EnCodec]:::ml
        end
        Generator[ML Generator]:::ml
        AudioProc[Audio Processing]:::ml
    end

    %% Database Layer
    DB[(Supabase DB)]:::database

    %% Relationships
    UI --> AR
    UI --> AP
    UI --> UV
    UI --> Auth
    UI --> Studio
    
    AR --> APIRouter
    AP --> APIRouter
    UV --> APIRouter
    Auth --> APIRouter
    Studio --> APIRouter
    
    APIRouter --> AuthC
    APIRouter --> AudioC
    
    AudioC --> FileHandler
    AudioC --> Storage
    AuthC --> DBConn
    
    DBConn --> DB
    
    AudioC --> MLAPI
    MLAPI --> Generator
    Generator --> ModelComponents
    Generator --> AudioProc

    %% Click Events
    click AR "https://github.com/12mv2/Harmony/blob/dev/src/components/core/AudioRecorder.tsx"
    click AP "https://github.com/12mv2/Harmony/blob/dev/src/components/core/AudioPlayer.tsx"
    click UV "https://github.com/12mv2/Harmony/blob/dev/src/components/features/UserVoice.tsx"
    click Auth "https://github.com/12mv2/Harmony/blob/dev/src/pages/Login.tsx"
    click Studio "https://github.com/12mv2/Harmony/blob/dev/src/pages/Studio.tsx"
    click APIRouter "https://github.com/12mv2/Harmony/blob/dev/src/server/routes/apiRouter.ts"
    click AuthC "https://github.com/12mv2/Harmony/blob/dev/src/server/controller/authController.ts"
    click AudioC "https://github.com/12mv2/Harmony/blob/dev/src/server/controller/audioController.ts"
    click FileHandler "https://github.com/12mv2/Harmony/blob/dev/src/server/controller/audioMiddleware.ts"
    click DBConn "https://github.com/12mv2/Harmony/blob/dev/src/server/model/db.ts"
    click Storage "https://github.com/12mv2/Harmony/blob/dev/src/server/model/storage.ts"
    click MLAPI "https://github.com/12mv2/Harmony/blob/dev/ml_service/api/main.py"
    click CLAP "https://github.com/12mv2/Harmony/tree/dev/ml_service/open_musiclm/laion_clap"
    click HuBERT "https://github.com/12mv2/Harmony/blob/dev/ml_service/open_musiclm/hf_hubert_kmeans.py"
    click EnCodec "https://github.com/12mv2/Harmony/blob/dev/ml_service/open_musiclm/encodec_wrapper.py"
    click Generator "https://github.com/12mv2/Harmony/blob/dev/ml_service/model/generator.py"
    click AudioProc "https://github.com/12mv2/Harmony/blob/dev/ml_service/open_musiclm/preprocess.py"
```
