# foamzou/melody architecture

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

- Interactive diagram: https://gitdiagram.com/foamzou/melody
- Repository: https://github.com/foamzou/melody

## Overview

##### Main System Components

a) Frontend Layer:
- PC Interface (Vue.js based)
- Mobile Interface (PWA-enabled)
- Shared Components (Player, Search Results, Task Notifications)

b) Backend Layer:
- API Server (Node.js)
- Service Modules
- Media Processing
- Platform Integration

c) External Services:
- Music Platforms (NetEase Cloud Music, etc.)
- Media Sources (Bilibili, Douyin, etc.)

##### Component Relationships

**[Frontend Layer]**
- ↑↓
**[Backend API Layer]**
- ↑↓
**[Service Layer]**
- ↑↓
**[External Services]**

##### Detailed Component Breakdown

- PC Views
- Home
- Account
- Playlist
- Settings
- Mobile Views
- Home
- Account
- Playlist
- Shared Components
- Player
- Search Results
- Task Notifications

- API Handlers
- Account Management
- Playlist Management
- Song Management
- Media Fetching
- Sync Jobs
- Services
- Media Fetcher
- Music Platform Integration
- Search Service
- Sync Service
- Config Management

- Music Platforms
- Media Sources
- Storage (Cloud Drive)

##### Data Flow Indicators

- User requests flow (frontend → backend)
- Media processing flow (external → backend → frontend)
- Storage operations (backend → cloud storage)
- Authentication flow (user → frontend → backend → music platforms)

##### Technical Stack Indicators

Technology labels:
- Frontend: Vue.js, PWA
- Backend: Node.js
- External Tools: FFmpeg
- Deployment: Docker

##### Mobile/PC interface separation

Keep the abstraction level focused on the main architectural components while showing the key interactions that make the system unique, such as the music unlocking feature and cross-platform media fetching capability.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef frontend fill:#3498db,color:white
    classDef backend fill:#2ecc71,color:white
    classDef external fill:#95a5a6,color:white
    classDef shared fill:#9b59b6,color:white
    classDef api fill:#e74c3c,color:white

    %% Frontend Layer
    subgraph Frontend
        PC["PC Interface"]
        Mobile["Mobile Interface"]
        Shared["Shared Components"]

        subgraph PCViews
            PCHome["Home View"]
            PCAccount["Account View"]
            PCPlaylist["Playlist View"]
            PCSettings["Settings View"]
        end

        subgraph MobileViews
            MobileHome["Home View"]
            MobileAccount["Account View"]
            MobilePlaylist["Playlist View"]
        end

        subgraph SharedComponents
            Player["Player"]
            SearchResults["Search Results"]
            TaskNotif["Task Notifications"]
        end

        PC --> PCViews
        Mobile --> MobileViews
        Shared --> SharedComponents
    end

    %% Backend Layer
    subgraph Backend
        APIHandlers["API Handlers"]
        Services["Service Modules"]

        subgraph Handlers
            AccountAPI["Account Management"]
            PlaylistAPI["Playlist Management"]
            SongAPI["Song Management"]
            MediaAPI["Media Fetching"]
            SyncAPI["Sync Jobs"]
        end

        subgraph ServiceModules
            MediaFetcher["Media Fetcher"]
            PlatformIntegration["Music Platform Integration"]
            SearchService["Search Service"]
            SyncService["Sync Service"]
            ConfigMgmt["Config Management"]
        end

        APIHandlers --> Handlers
        Services --> ServiceModules
    end

    %% External Services
    subgraph External
        MusicPlatforms["Music Platforms"]
        MediaSources["Media Sources"]
        CloudStorage["Storage (Cloud Drive)"]
    end

    %% Connections
    Frontend <--> APIHandlers
    APIHandlers <--> Services
    Services <--> External

    %% Click Events
    click PC "https://github.com/foamzou/melody/tree/main/frontend/src/views/pc/"
    click Mobile "https://github.com/foamzou/melody/tree/main/frontend/src/views/mobile/"
    click Shared "https://github.com/foamzou/melody/tree/main/frontend/src/components/"
    click PCHome "https://github.com/foamzou/melody/blob/main/frontend/src/views/pc/Home.vue"
    click PCAccount "https://github.com/foamzou/melody/blob/main/frontend/src/views/pc/Account.vue"
    click PCPlaylist "https://github.com/foamzou/melody/blob/main/frontend/src/views/pc/Playlist.vue"
    click PCSettings "https://github.com/foamzou/melody/blob/main/frontend/src/views/pc/Setting.vue"
    click MobileHome "https://github.com/foamzou/melody/blob/main/frontend/src/views/mobile/Home.vue"
    click MobileAccount "https://github.com/foamzou/melody/blob/main/frontend/src/views/mobile/Account.vue"
    click MobilePlaylist "https://github.com/foamzou/melody/blob/main/frontend/src/views/mobile/Playlist.vue"
    click Player "https://github.com/foamzou/melody/blob/main/frontend/src/components/Player.vue"
    click SearchResults "https://github.com/foamzou/melody/blob/main/frontend/src/components/SearchResultTable.vue"
    click TaskNotif "https://github.com/foamzou/melody/blob/main/frontend/src/components/TaskNotification.js"
    click AccountAPI "https://github.com/foamzou/melody/blob/main/backend/src/handler/account.js"
    click PlaylistAPI "https://github.com/foamzou/melody/blob/main/backend/src/handler/playlists.js"
    click SongAPI "https://github.com/foamzou/melody/blob/main/backend/src/handler/songs.js"
    click MediaAPI "https://github.com/foamzou/melody/blob/main/backend/src/handler/media_fetcher_lib.js"
    click SyncAPI "https://github.com/foamzou/melody/blob/main/backend/src/handler/sync_jobs.js"
    click MediaFetcher "https://github.com/foamzou/melody/tree/main/backend/src/service/media_fetcher/"
    click PlatformIntegration "https://github.com/foamzou/melody/tree/main/backend/src/service/music_platform/"
    click SearchService "https://github.com/foamzou/melody/tree/main/backend/src/service/search_songs/"
    click SyncService "https://github.com/foamzou/melody/tree/main/backend/src/service/sync_music/"
    click ConfigMgmt "https://github.com/foamzou/melody/tree/main/backend/src/service/config_manager/"

    %% Style Applications
    class PC,Mobile,PCViews,MobileViews frontend
    class APIHandlers,Services,Handlers,ServiceModules backend
    class MusicPlatforms,MediaSources,CloudStorage external
    class Shared,SharedComponents shared
    class AccountAPI,PlaylistAPI,SongAPI,MediaAPI,SyncAPI api
```
