# clash-projects/lastwave-desktop architecture

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

- Interactive diagram: https://gitdiagram.com/clash-projects/lastwave-desktop
- Repository: https://github.com/clash-projects/lastwave-desktop

## Overview

LastWave is a desktop music player. Its principal workflow is listening to music through playback, with the UI also exposing synced lyrics, smart playlists, YouTube Music, and Last.fm scrobbling. The README documents these product capabilities but does not show the Dart runtime wiring, so feature-level connections are documented at a high level only. Native Windows and Linux startup and Windows audio-channel relationships are supported by the sampled source; unsampled Dart internals are represented by their exact tree paths.

Main entry points: [`lib/main.dart`](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/main.dart) (LastWave app), [`linux/runner/my_application.cc`](https://github.com/clash-projects/lastwave-desktop/blob/main/linux/runner/my_application.cc) (Linux app host), [`windows/runner/main.cpp`](https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/main.cpp) (Windows launcher), [`windows/runner/flutter_window.cpp`](https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/flutter_window.cpp) (Flutter window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_app["LastWave app<br/>[main.dart]"]
  node_shell["App shell<br/>[app_shell.dart]"]
  node_collections["Library views"]
end

subgraph group_playback["Playback and audio"]
  node_player["Playback service"]
  node_playerstate["Player state<br/>[player_state.dart]"]
  node_lossless["Lossless source"]
  node_audioout["Audio output"]
end

subgraph group_music["Music services"]
  node_youtube["YouTube Music<br/>[innertube_api.dart]"]
  node_search["Music search"]
  node_downloads["Downloads"]
end

subgraph group_personal["Personal features"]
  node_lyrics["Synced lyrics"]
  node_smartmix["Smart playlists<br/>[local_taste.dart]"]
  node_lastfm["Last.fm scrobbling"]
  node_database[("App database<br/>[app_database.dart]")]
end

subgraph group_platform["Platform integration"]
  node_winmain["Windows launcher<br/>[main.cpp]"]
  node_flutterwindow["Flutter window<br/>[flutter_window.cpp]"]
  node_wasapichannel["WASAPI channel<br/>[wasapi_channel.cpp]"]
  node_wasapiengine["WASAPI engine<br/>[wasapi_engine.cpp]"]
  node_linuxapp["Linux app host<br/>[my_application.cc]"]
  node_pluginreg["Linux plugins"]
  node_webviewguard["WebView guard<br/>[yt_webview_guard.h]"]
end

node_user(("Listener"))

node_user -->|"uses"| node_app
node_app -->|"plays music"| node_player
node_app -->|"shows lyrics"| node_lyrics
node_app -->|"generates playlists"| node_smartmix
node_app -->|"scrobbles listens"| node_lastfm
node_app -->|"integrates"| node_youtube
node_app -->|"starts on Windows"| node_winmain
node_winmain -->|"creates window"| node_flutterwindow
node_flutterwindow -->|"owns channel"| node_wasapichannel
node_wasapichannel -->|"uses"| node_wasapiengine
node_app -->|"starts on Linux"| node_linuxapp
node_linuxapp -->|"registers plugins"| node_pluginreg
node_linuxapp -->|"registers guard"| node_webviewguard

click node_app "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/main.dart"
click node_shell "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/ui/app_shell/app_shell.dart"
click node_collections "https://github.com/clash-projects/lastwave-desktop/tree/main/lib/ui/collections"
click node_player "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/player/playback_service.dart"
click node_playerstate "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/player/player_state.dart"
click node_lossless "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/lossless/lossless_source.dart"
click node_audioout "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/audio_output/output_controller.dart"
click node_lyrics "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/lyrics/lyrics_repository.dart"
click node_smartmix "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/feed/local_taste.dart"
click node_lastfm "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/lastfm/scrobble_repository.dart"
click node_youtube "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/innertube/innertube_api.dart"
click node_search "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/search/search_repository.dart"
click node_downloads "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/downloads/download_manager.dart"
click node_database "https://github.com/clash-projects/lastwave-desktop/blob/main/lib/core/storage/app_database.dart"
click node_winmain "https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/main.cpp"
click node_flutterwindow "https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/flutter_window.cpp"
click node_wasapichannel "https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/wasapi_channel.cpp"
click node_wasapiengine "https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/wasapi_engine.cpp"
click node_linuxapp "https://github.com/clash-projects/lastwave-desktop/blob/main/linux/runner/my_application.cc"
click node_pluginreg "https://github.com/clash-projects/lastwave-desktop/blob/main/linux/flutter/generated_plugin_registrant.cc"
click node_webviewguard "https://github.com/clash-projects/lastwave-desktop/blob/main/linux/runner/yt_webview_guard.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_app,node_shell,node_collections toneBlue
class node_player,node_playerstate,node_lossless,node_audioout toneAmber
class node_youtube,node_search,node_downloads toneMint
class node_lyrics,node_smartmix,node_lastfm,node_database toneRose
class node_winmain,node_flutterwindow,node_wasapichannel,node_wasapiengine,node_linuxapp,node_pluginreg,node_webviewguard,node_user toneIndigo
```

## Components

### Desktop experience

- [LastWave app](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/main.dart): `lib/main.dart`
- [App shell](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/ui/app_shell/app_shell.dart): `lib/ui/app_shell/app_shell.dart`
- [Library views](https://github.com/clash-projects/lastwave-desktop/tree/main/lib/ui/collections): `lib/ui/collections`

### Playback and audio

- [Playback service](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/player/playback_service.dart): `lib/features/player/playback_service.dart`
- [Player state](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/player/player_state.dart): `lib/features/player/player_state.dart`
- [Lossless source](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/lossless/lossless_source.dart): `lib/features/lossless/lossless_source.dart`
- [Audio output](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/audio_output/output_controller.dart): `lib/features/audio_output/output_controller.dart`

### Music services

- [YouTube Music](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/innertube/innertube_api.dart): `lib/features/innertube/innertube_api.dart`
- [Music search](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/search/search_repository.dart): `lib/features/search/search_repository.dart`
- [Downloads](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/downloads/download_manager.dart): `lib/features/downloads/download_manager.dart`

### Personal features

- [Synced lyrics](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/lyrics/lyrics_repository.dart): `lib/features/lyrics/lyrics_repository.dart`
- [Smart playlists](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/feed/local_taste.dart): `lib/features/feed/local_taste.dart`
- [Last.fm scrobbling](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/features/lastfm/scrobble_repository.dart): `lib/features/lastfm/scrobble_repository.dart`
- [App database](https://github.com/clash-projects/lastwave-desktop/blob/main/lib/core/storage/app_database.dart): `lib/core/storage/app_database.dart`

### Platform integration

- [Windows launcher](https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/main.cpp): `windows/runner/main.cpp`
- [Flutter window](https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/flutter_window.cpp): `windows/runner/flutter_window.cpp`
- [WASAPI channel](https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/wasapi_channel.cpp): `windows/runner/wasapi_channel.cpp`
- [WASAPI engine](https://github.com/clash-projects/lastwave-desktop/blob/main/windows/runner/wasapi_engine.cpp): `windows/runner/wasapi_engine.cpp`
- [Linux app host](https://github.com/clash-projects/lastwave-desktop/blob/main/linux/runner/my_application.cc): `linux/runner/my_application.cc`
- [Linux plugins](https://github.com/clash-projects/lastwave-desktop/blob/main/linux/flutter/generated_plugin_registrant.cc): `linux/flutter/generated_plugin_registrant.cc`
- [WebView guard](https://github.com/clash-projects/lastwave-desktop/blob/main/linux/runner/yt_webview_guard.h): `linux/runner/yt_webview_guard.h`

### Other components

- **Listener**

## Connections

- Listener → LastWave app: uses (evidence: `README.md`)
- LastWave app → Playback service: plays music (evidence: `README.md`)
- LastWave app → Synced lyrics: shows lyrics (evidence: `README.md`)
- LastWave app → Smart playlists: generates playlists (evidence: `README.md`)
- LastWave app → Last.fm scrobbling: scrobbles listens (evidence: `README.md`)
- LastWave app → YouTube Music: integrates (evidence: `README.md`)
- LastWave app → Windows launcher: starts on Windows (evidence: `windows/runner/main.cpp`)
- Windows launcher → Flutter window: creates window (evidence: `windows/runner/main.cpp`)
- Flutter window → WASAPI channel: owns channel
- WASAPI channel → WASAPI engine: uses (evidence: `windows/runner/wasapi_channel.cpp`)
- LastWave app → Linux app host: starts on Linux
- Linux app host → Linux plugins: registers plugins (evidence: `linux/runner/my_application.cc`)
- Linux app host → WebView guard: registers guard (evidence: `linux/runner/my_application.cc`)
