# jayfunc/betterlyrics architecture

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

- Interactive diagram: https://gitdiagram.com/jayfunc/betterlyrics
- Repository: https://github.com/jayfunc/betterlyrics

## Overview

1. **Repository shape**
   - This is a multi-project .NET solution centered on a lyrics visualizer/music player.
   - The main production app is **BetterLyrics.WinUI3** for Windows.
   - A second UI stack, **BetterLyrics.Avalonia**, provides a cross-platform client with Desktop, Browser, Android, and iOS hosts.
   - **BetterLyrics.Core** holds the shared domain, logic, and persistence models.
   - **BetterLyrics.Sdk** is the public plugin contract layer.

2. **Shared core boundary**
   - `BetterLyrics.Core` is the architecture’s stable foundation: enums, models, helpers, interfaces, and database entities.
   - It defines the app’s concepts such as lyrics formats, window modes, settings structures, playback/statistics models, and service abstractions.
   - The UI projects and service implementations depend on Core, not the other way around.

3. **Main Windows app shell**
   - `BetterLyrics.WinUI3` is the feature-rich desktop client built with **WinUI 3** and **Win2D**.
   - It contains the app bootstrap, pages/windows, view models, converters, themes, and visual controls.
   - The UI is organized as many specialized surfaces: Now Playing, Music Gallery, Lyrics Search, Settings, Stats Dashboard, Lyrics Share, System Tray, and Toast Overlay.
   - This project is the one that exposes the full Windows-native experience described in the README.

4. **Rendering pipeline**
   - The WinUI3 project has a dedicated rendering subsystem under `Renderer`, `Shaders`, and `Helper/Lyrics`.
   - Renderers compose the visual output for lyrics, backgrounds, spectrum visualization, and special effects such as fog, snow, raindrops, and fluid backgrounds.
   - Lyrics rendering is split by layout direction, with separate horizontal and vertical strategies and line renderers.
   - The data flow here is: lyric data and playback state in → render model/layout calculation → composition/Win2D drawing out.

5. **Lyrics processing pipeline**
   - `BetterLyrics.Core.Helpers.Lyrics` handles parsing, conversion, metadata extraction, and layout support for lyrics files.
   - Supported formats include LRC, enhanced/extended variants, QRC/KRC, and TTML.
   - Lyrics are normalized, filtered, and transformed before they reach the renderer.
   - This is one of the main business pipelines: lyric source input → parse/convert → cache/search → render.

6. **Playback and media integration**
   - The app is not just a visualizer; it integrates with external players and system playback state.
   - WinUI3 services include SMTC/GSMTC, playback memory/history, song search mapping, and album-art updates.
   - Hook classes such as `GlobalHotKeyHook`, `AudioMixerHook`, `SystemThemeHook`, `TaskbarHook`, and `WindowHook` show strong OS-level integration.
   - These hooks and services turn system/player events into app state changes that drive the UI and rendering.

7. **Storage and persistence**
   - Persistent data is split into several SQLite-style DbContexts in Core: `FilesIndexDbContext`, `LyricsCacheDbContext`, `PlayHistoryDbContext`, and `SongSearchMapDbContext`.
   - The app keeps separate concerns for indexed media files, cached lyrics, playback history, and mapped search queries.
   - `SettingsService` and `SettingsIO` manage app configuration, while resource/profile files define saved window layouts and statuses.
   - This creates a clear boundary between transient runtime state and persisted app knowledge.

8. **Media/file-system abstraction**
   - File access is abstracted behind `IFileSystemService` and `IUnifiedFileSystem`.
   - Implementations support local storage as well as remote sources such as **SMB, WebDAV, and FTP**.
   - A file-watch service keeps the library synchronized with filesystem changes.
   - This subsystem feeds the library/indexing and playback layers rather than being owned by the UI.

9. **Search, translation, and enrichment services**
   - Lyrics acquisition is handled by search services and provider abstractions.
   - The repo references external lyrics and metadata ecosystems such as Apple Music, LRCLIB, and offline translation via LibreTranslate.
   - Additional services cover transliteration, translation, and lyrics cache lookup.
   - In architecture terms, these are enrichment adapters that sit between the media/song identity layer and the final rendered lyrics.

10. **Plugin architecture**
   - `BetterLyrics.Sdk` defines the plugin-facing contracts for lyrics sources, translators, transliterators, AI services, configurators, and localization.
   - Core’s plugin service loads plugins with isolated contexts/loaders and metadata helpers.
   - This means third-party extensions can inject new lyrics sources or text-processing behaviors without changing the core app.
   - The plugin boundary is explicit: SDK interfaces on one side, host-owned loading/runtime services on the other.

11. **UI architecture on Windows**
   - The WinUI3 app uses a classic MVVM split: Views, ViewModels, Controls, Converters, and Services.
   - The UI is heavily componentized for settings and feature modules, such as lyrics styling, window behavior, playback settings, plugins, and stats.
   - Specialized windows like lyrics search/share and the window switcher indicate that the app supports multiple operational modes, not just a single main window.
   - System tray and toast overlay components show that the app also behaves like a background utility.

12. **Cross-platform Avalonia client**
   - `BetterLyrics.Avalonia` mirrors the app concept in a separate UI stack using **Avalonia**.
   - It has shared app code plus platform hosts for Desktop, Browser, Android, and iOS.
   - This project appears narrower than WinUI3, but architecturally it follows the same pattern: shared services/viewmodels plus platform entry points.
   - For a diagram, it should be treated as a parallel client family backed by the shared Core layer.

13. **External integrations and distribution**
   - Runtime integrations include **Discord Rich Presence**, **Last.fm scrobbling**, and Microsoft shell features like SMTC.
   - The repository also contains GitHub Actions for store-app builds, issue translation, and release notifications to Discord/Telegram.
   - These are not core business logic, but they matter because they connect the app to external services and the release pipeline.

14. **What to show in an architecture diagram**
   - Put `BetterLyrics.Core` and `BetterLyrics.Sdk` in the center as shared foundations.
   - Show `BetterLyrics.WinUI3` as the main host with arrows to file/media sources, lyric search providers, cache/history databases, OS hooks, and external services.
   - Show the rendering subsystem as a separate internal pipeline fed by playback state and lyrics data.
   - Show `BetterLyrics.Avalonia` as a second host sharing Core/SDK but with its own platform-specific shells.

Main entry points: [`src/BetterLyrics.WinUI3/BetterLyrics.WinUI3`](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3) (WinUI3 app), [`src/BetterLyrics.Core`](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core) (BetterLyrics.Core), [`src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Services`](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Services) (App services), [`src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Renderer`](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Renderer) (Rendering pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_foundation["Shared foundation"]
  node_core["BetterLyrics.Core<br/>shared core<br/>[BetterLyrics.Core]"]
  node_sdk["BetterLyrics.Sdk<br/>plugin sdk<br/>[BetterLyrics.Sdk]"]
  node_core_lyrics["Lyrics pipeline<br/>parse/convert<br/>[Lyrics]"]
  node_core_storage[("Persistence models<br/>dbcontexts<br/>[DbContext]")]
  node_core_media["Media abstraction<br/>file systems<br/>[FileSystemService]"]
  node_core_plugins["Plugin runtime<br/>host runtime<br/>[PluginService]"]
end

subgraph group_winui["Windows client"]
  node_winui_app["WinUI3 app<br/>windows host"]
  node_winui_ui["UI surfaces<br/>mvvm views<br/>[Views]"]
  node_winui_settings["Settings modules<br/>ui controls<br/>[Controls]"]
  node_winui_render["Rendering pipeline<br/>draw/composite<br/>[Renderer]"]
  node_winui_lyrics["Lyrics layout<br/>render strategy<br/>[Lyrics]"]
  node_winui_services["App services<br/>runtime services<br/>[Services]"]
  node_winui_hooks["OS hooks<br/>system integration<br/>[Hooks]"]
  node_winui_models["Render models<br/>ui state<br/>[Lyrics]"]
end

subgraph group_avalonia["Avalonia client"]
  node_avalonia_app["Avalonia app<br/>cross-platform host"]
  node_avalonia_hosts["Platform hosts<br/>entrypoints"]
  node_avalonia_services["Client services<br/>app services<br/>[Services]"]
end

subgraph group_integration["External integrations"]
  node_external_services(("External services<br/>integrations"))
end

node_winui_app -->|"depends on"| node_core
node_winui_app -->|"loads plugins"| node_sdk
node_avalonia_app -->|"depends on"| node_core
node_avalonia_app -->|"uses contracts"| node_sdk
node_core -->|"contains"| node_core_lyrics
node_core -->|"contains"| node_core_storage
node_core -->|"contains"| node_core_media
node_core -->|"contains"| node_core_plugins
node_winui_app -->|"composes"| node_winui_ui
node_winui_app -->|"composes"| node_winui_settings
node_winui_app -->|"drives"| node_winui_render
node_winui_app -->|"coordinates"| node_winui_services
node_winui_app -->|"integrates"| node_winui_hooks
node_winui_render -->|"uses"| node_winui_lyrics
node_winui_render -->|"consumes"| node_winui_models
node_winui_services -->|"persists to"| node_core_storage
node_winui_services -->|"reads from"| node_core_media
node_winui_services -->|"calls"| node_external_services
node_winui_hooks -.->|"bridges"| node_external_services
node_avalonia_services -->|"persists to"| node_core_storage
node_avalonia_services -->|"calls"| node_external_services
node_sdk -.->|"implemented by"| node_core_plugins
node_core_lyrics -->|"feeds"| node_winui_render

click node_core "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core"
click node_sdk "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Sdk"
click node_core_lyrics "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Helpers/Lyrics"
click node_core_storage "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Models/DbContext"
click node_core_media "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Implementations/Services/FileSystemService"
click node_core_plugins "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Implementations/Services/PluginService"
click node_winui_app "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3"
click node_winui_ui "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Views"
click node_winui_settings "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Controls"
click node_winui_render "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Renderer"
click node_winui_lyrics "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Helper/Lyrics"
click node_winui_services "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Services"
click node_winui_hooks "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Hooks"
click node_winui_models "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Models/Lyrics"
click node_avalonia_app "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Avalonia/BetterLyrics.Avalonia"
click node_avalonia_hosts "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Avalonia"
click node_avalonia_services "https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Avalonia/BetterLyrics.Avalonia/Services"

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_core,node_sdk,node_core_lyrics,node_core_storage,node_core_media,node_core_plugins toneBlue
class node_winui_app,node_winui_ui,node_winui_settings,node_winui_render,node_winui_lyrics,node_winui_services,node_winui_hooks,node_winui_models toneAmber
class node_avalonia_app,node_avalonia_hosts,node_avalonia_services toneMint
class node_external_services toneRose
```

## Components

### Shared foundation

Core domain models, helpers, persistence, and plugin contracts used across clients.

- [BetterLyrics.Core](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core): shared core · Stable shared foundation for domain concepts, lyrics processing, storage models, and service abstractions. · `src/BetterLyrics.Core`
- [BetterLyrics.Sdk](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Sdk): plugin sdk · Public plugin contract layer for lyrics sources, translators, configurators, localizers, and AI services. · `src/BetterLyrics.Sdk`
- [Lyrics pipeline](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Helpers/Lyrics): parse/convert · Shared lyrics parsing, conversion, metadata extraction, and layout helpers for LRC, QRC/KRC, and TTML. · `src/BetterLyrics.Core/Helpers/Lyrics`
- [Persistence models](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Models/DbContext): dbcontexts · SQLite-style contexts and entities for files index, lyrics cache, play history, and song-search mapping. · `src/BetterLyrics.Core/Models/DbContext`
- [Media abstraction](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Implementations/Services/FileSystemService): file systems · Unified file-system contracts and implementations for local and remote sources such as SMB, WebDAV, and FTP. · `src/BetterLyrics.Core/Implementations/Services/FileSystemService`
- [Plugin runtime](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Core/Implementations/Services/PluginService): host runtime · Plugin loading, isolated contexts, configuration, and localization support on the host side. · `src/BetterLyrics.Core/Implementations/Services/PluginService`

### Windows client

Main WinUI 3 application with UI, services, hooks, and rendering pipeline.

- [WinUI3 app](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3): windows host · Feature-rich Windows shell with bootstrap, navigation, MVVM, and app-wide composition. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3`
- [UI surfaces](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Views): mvvm views · Main Windows screens and controls for now playing, gallery, search, settings, stats, share, tray, and overlays. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Views`
- [Settings modules](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Controls): ui controls · Componentized settings and configuration panels for playback, lyrics styling, window behavior, media, and plugins. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Controls`
- [Rendering pipeline](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Renderer): draw/composite · Composition and Win2D rendering pipeline for lyrics, backgrounds, spectrum, and visual effects. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Renderer`
- [Lyrics layout](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Helper/Lyrics): render strategy · Horizontal and vertical layout strategies plus line renderers that turn normalized lyric data into visual regions. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Helper/Lyrics`
- [App services](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Services): runtime services · Runtime services for playback, search, cache, history, localization, updates, translation, and plugin hosting. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Services`
- [OS hooks](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Hooks): system integration · Windows hooks for hotkeys, audio mix, theme, taskbar, window, IME, monitor, and worker-window behavior. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Hooks`
- [Render models](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Models/Lyrics): ui state · Windows-specific lyrics render models and window-tracking state used by the shell and renderer. · `src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Models/Lyrics`

### Avalonia client

Cross-platform client family with shared app code and platform hosts.

- [Avalonia app](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Avalonia/BetterLyrics.Avalonia): cross-platform host · Shared Avalonia client code with its own shell, services, view models, and views. · `src/BetterLyrics.Avalonia/BetterLyrics.Avalonia`
- [Platform hosts](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Avalonia): entrypoints · Desktop, browser, Android, and iOS host projects for the Avalonia client family. · `src/BetterLyrics.Avalonia`
- [Client services](https://github.com/jayfunc/betterlyrics/blob/dev/src/BetterLyrics.Avalonia/BetterLyrics.Avalonia/Services): app services · Avalonia-side update, localization, cache, and settings services built on shared abstractions. · `src/BetterLyrics.Avalonia/BetterLyrics.Avalonia/Services`

### External integrations

Third-party services and OS-level integrations that feed the app experience.

- **External services**: integrations · Lyrics providers, translation services, Discord/Last.fm, and Microsoft shell integrations consumed by the app.

## Connections

- WinUI3 app → BetterLyrics.Core: depends on · Windows host builds on shared domain, settings, and persistence contracts.
- WinUI3 app → BetterLyrics.Sdk: loads plugins · WinUI3 host exposes the plugin boundary through shared SDK contracts.
- Avalonia app → BetterLyrics.Core: depends on · Avalonia client shares the same foundation models and abstractions.
- Avalonia app → BetterLyrics.Sdk: uses contracts · Avalonia client can participate in the same plugin contract layer.
- BetterLyrics.Core → Lyrics pipeline: contains · Shared helpers implement lyrics parsing, conversion, and layout support.
- BetterLyrics.Core → Persistence models: contains · Shared database contexts and entities model persisted app state.
- BetterLyrics.Core → Media abstraction: contains · Shared file-system abstractions and providers live in the core layer.
- BetterLyrics.Core → Plugin runtime: contains · Core owns plugin loading/runtime infrastructure.
- WinUI3 app → UI surfaces: composes · Main app shell navigates to the production views and windows.
- WinUI3 app → Settings modules: composes · Settings features are split into specialized controls and panels.
- WinUI3 app → Rendering pipeline: drives · Playback and lyric state feed the Windows rendering pipeline.
- WinUI3 app → App services: coordinates · Shell orchestration and app behavior are implemented by services.
- WinUI3 app → OS hooks: integrates · Windows-specific OS hooks are attached at the host boundary.
- Rendering pipeline → Lyrics layout: uses · Renderer delegates lyric layout and line composition to the layout strategies.
- Rendering pipeline → Render models: consumes · Renderers consume renderable lyric models and window state.
- App services → Persistence models: persists to · Caching, history, and file indexing flow into the shared database layer.
- App services → Media abstraction: reads from · Media and file-system services rely on unified local/remote access.
- App services → External services: calls · Lyrics search, translation, Discord, Last.fm, and SMTC integrate through service adapters.
- OS hooks → External services: bridges · OS hooks translate system events into app state and external integration flows.
- Client services → Persistence models: persists to · Avalonia client reuses shared persistence concepts for cache and settings.
- Client services → External services: calls · Cross-platform client services reach out to update and localization backends.
- BetterLyrics.Sdk → Plugin runtime: implemented by · Host-side plugin runtime fulfills the public contracts declared in the SDK.
- Lyrics pipeline → Rendering pipeline: feeds · Normalized lyric data and layout metadata flow into rendering.
