# solohomie/cloudsong architecture

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

- Interactive diagram: https://gitdiagram.com/solohomie/cloudsong
- Repository: https://github.com/solohomie/cloudsong

## Overview

CloudSong is a Qt/C++ desktop music player whose UI is currently mock-driven, with a working plugin-service/runtime path for MusicFree-compatible music operations. The principal flow is a QML request through PluginService, platform selection and dispatch into an isolated QuickJS worker, then a result signal back to the UI. The repository also includes recommendation, configuration, input-key utilities and taskbar controls. Plugin loading and QuickJS support are documented or indexed, but most implementation details were not excerpted; edges reflect only visible or documented relationships.

Main entry points: [`src/app/main.cpp`](https://github.com/solohomie/cloudsong/blob/main/src/app/main.cpp) (App Bootstrap), [`src/services/pluginruntime.cpp`](https://github.com/solohomie/cloudsong/blob/main/src/services/pluginruntime.cpp) (Plugin Runtime), [`src/services/pluginservice.cpp`](https://github.com/solohomie/cloudsong/blob/main/src/services/pluginservice.cpp) (Plugin Facade), [`src/services/pluginruntime_worker.h`](https://github.com/solohomie/cloudsong/blob/main/src/services/pluginruntime_worker.h) (Runtime Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Services"]
  node_main["App Bootstrap<br/>[main.cpp]"]
  node_config["App Config<br/>[appconfig.cpp]"]
  node_input["Input Service<br/>[inputservice.cpp]"]
  node_recommend["Recommendations"]
  node_taskbar["Taskbar Controls"]
end

subgraph group_plugins["Plugin Integration"]
  node_pluginservice["Plugin Facade<br/>[pluginservice.cpp]"]
  node_pluginruntime["Plugin Runtime<br/>[pluginruntime.cpp]"]
  node_worker["Runtime Worker"]
  node_pluginfiles["Music Plugins"]
  node_pluginlibs["Plugin Libraries"]
end

subgraph group_js["JavaScript Runtime"]
end

subgraph group_vendor["QuickJS Engine"]
  node_quickjs["QuickJS Engine<br/>[quickjs.c]"]
  node_regexp["Regex Engine<br/>[libregexp.c]"]
  node_unicode["Unicode Support<br/>[libunicode.c]"]
  node_dtoa["Number Conversion<br/>[dtoa.c]"]
  node_cutils["C Utilities<br/>[cutils.h]"]
end

node_qml["QML UI"]
node_actor(("Listener"))
node_network(("Web Services"))

node_qml -.->|"requests methods"| node_pluginservice
node_pluginservice -->|"dispatches calls"| node_pluginruntime
node_pluginruntime -->|"uses worker"| node_worker
node_worker -->|"executes with"| node_quickjs
node_pluginruntime -->|"loads plugins"| node_pluginfiles
node_pluginruntime -->|"loads modules"| node_pluginlibs
node_pluginservice -->|"downloads plugins"| node_network
node_main -->|"registers context"| node_config
node_main -->|"registers context"| node_input
node_main -->|"registers context"| node_pluginservice
node_main -->|"registers context"| node_recommend
node_main -->|"registers service"| node_taskbar
node_actor -.->|"uses player"| node_qml
node_regexp -->|"uses Unicode"| node_unicode
node_dtoa -->|"uses utilities"| node_cutils

click node_qml "https://github.com/solohomie/cloudsong/tree/main/qml"
click node_main "https://github.com/solohomie/cloudsong/blob/main/src/app/main.cpp"
click node_config "https://github.com/solohomie/cloudsong/blob/main/src/core/appconfig.cpp"
click node_input "https://github.com/solohomie/cloudsong/blob/main/src/services/inputservice.cpp"
click node_recommend "https://github.com/solohomie/cloudsong/blob/main/src/services/recommendservice.cpp"
click node_taskbar "https://github.com/solohomie/cloudsong/blob/main/src/services/taskbarbarservice.cpp"
click node_pluginservice "https://github.com/solohomie/cloudsong/blob/main/src/services/pluginservice.cpp"
click node_pluginruntime "https://github.com/solohomie/cloudsong/blob/main/src/services/pluginruntime.cpp"
click node_worker "https://github.com/solohomie/cloudsong/blob/main/src/services/pluginruntime_worker.h"
click node_pluginfiles "https://github.com/solohomie/cloudsong/tree/main/plugins"
click node_pluginlibs "https://github.com/solohomie/cloudsong/tree/main/plugins/lib"
click node_quickjs "https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/quickjs.c"
click node_regexp "https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/libregexp.c"
click node_unicode "https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/libunicode.c"
click node_dtoa "https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/dtoa.c"
click node_cutils "https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/cutils.h"

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_main,node_config,node_input,node_recommend,node_taskbar,node_qml toneBlue
class node_pluginservice,node_pluginruntime,node_worker,node_pluginfiles,node_pluginlibs toneAmber
class node_quickjs,node_regexp,node_unicode,node_dtoa,node_cutils toneRose
class node_actor,node_network toneIndigo
```

## Components

### App Services

- [App Bootstrap](https://github.com/solohomie/cloudsong/blob/main/src/app/main.cpp): `src/app/main.cpp`
- [App Config](https://github.com/solohomie/cloudsong/blob/main/src/core/appconfig.cpp): `src/core/appconfig.cpp`
- [Input Service](https://github.com/solohomie/cloudsong/blob/main/src/services/inputservice.cpp): `src/services/inputservice.cpp`
- [Recommendations](https://github.com/solohomie/cloudsong/blob/main/src/services/recommendservice.cpp): `src/services/recommendservice.cpp`
- [Taskbar Controls](https://github.com/solohomie/cloudsong/blob/main/src/services/taskbarbarservice.cpp): `src/services/taskbarbarservice.cpp`

### Plugin Integration

- [Plugin Facade](https://github.com/solohomie/cloudsong/blob/main/src/services/pluginservice.cpp): `src/services/pluginservice.cpp`
- [Plugin Runtime](https://github.com/solohomie/cloudsong/blob/main/src/services/pluginruntime.cpp): `src/services/pluginruntime.cpp`
- [Runtime Worker](https://github.com/solohomie/cloudsong/blob/main/src/services/pluginruntime_worker.h): `src/services/pluginruntime_worker.h`
- [Music Plugins](https://github.com/solohomie/cloudsong/tree/main/plugins): `plugins`
- [Plugin Libraries](https://github.com/solohomie/cloudsong/tree/main/plugins/lib): `plugins/lib`

### QuickJS Engine

- [QuickJS Engine](https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/quickjs.c): `3rdparty/quickjs/quickjs.c`
- [Regex Engine](https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/libregexp.c): `3rdparty/quickjs/libregexp.c`
- [Unicode Support](https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/libunicode.c): `3rdparty/quickjs/libunicode.c`
- [Number Conversion](https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/dtoa.c): `3rdparty/quickjs/dtoa.c`
- [C Utilities](https://github.com/solohomie/cloudsong/blob/main/3rdparty/quickjs/cutils.h): `3rdparty/quickjs/cutils.h`

### Other components

- [QML UI](https://github.com/solohomie/cloudsong/tree/main/qml): `qml`
- **Listener**
- **Web Services**

## Connections

- QML UI → Plugin Facade: requests methods
- Plugin Facade → Plugin Runtime: dispatches calls (evidence: `src/services/pluginservice.cpp`)
- Plugin Runtime → Runtime Worker: uses worker (evidence: `src/services/pluginruntime.cpp`)
- Runtime Worker → QuickJS Engine: executes with (evidence: `src/services/pluginruntime_worker.h`)
- Plugin Runtime → Music Plugins: loads plugins
- Plugin Runtime → Plugin Libraries: loads modules
- Plugin Facade → Web Services: downloads plugins (evidence: `src/services/pluginservice.cpp`)
- App Bootstrap → App Config: registers context (evidence: `src/app/main.cpp`)
- App Bootstrap → Input Service: registers context (evidence: `src/app/main.cpp`)
- App Bootstrap → Plugin Facade: registers context (evidence: `src/app/main.cpp`)
- App Bootstrap → Recommendations: registers context (evidence: `src/app/main.cpp`)
- App Bootstrap → Taskbar Controls: registers service
- Listener → QML UI: uses player
- Regex Engine → Unicode Support: uses Unicode (evidence: `3rdparty/quickjs/libregexp.c`)
- Number Conversion → C Utilities: uses utilities (evidence: `3rdparty/quickjs/dtoa.c`)
