# blueangelcpt/resonance architecture

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

- Interactive diagram: https://gitdiagram.com/blueangelcpt/resonance
- Repository: https://github.com/blueangelcpt/resonance

## Overview

Resonance is a native MP3 library manager and player with CLI and Qt desktop entry points sharing an application engine. The principal workflow is to scan read-only sources into a catalogue, group albums and enrich them, review uncertain decisions, compute a non-writing change plan, export safe organised copies, then verify or recover interrupted work. The README also documents local BPM analysis, artwork and lyrics lookup, privacy and gain cleaning, playback, and artwork review. The graph follows documented workflows and sampled call sites; unsampled implementation details are represented only where the tree supports a path.

Main entry points: [`src/MusicLibrary.Application/src/LibraryEnrichment.cpp`](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/LibraryEnrichment.cpp) (Enrichment and export), [`src/MusicLibrary.Desktop/src/MainWindow.cpp`](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/MainWindow.cpp) (Desktop workbench), [`src/MusicLibrary.Application/include/mlapp/Library.hpp`](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/include/mlapp/Library.hpp) (Library engine), [`src/MusicLibrary.Application/src/Library.cpp`](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/Library.cpp) (Scan and catalogue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_cli["CLI commands<br/>[main.cpp]"]
  node_desktopapp["Desktop app<br/>[main.cpp]"]
end

subgraph group_application["Library workflow"]
  node_library["Library engine<br/>[Library.hpp]"]
  node_scan["Scan and catalogue<br/>[Library.cpp]"]
  node_enrichment["Enrichment and export"]
  node_catalogue["Catalogue repository<br/>[Catalogue.cpp]"]
end

subgraph group_domain["Domain decisions"]
  node_albumgroup["Album grouping<br/>[AlbumGrouping.cpp]"]
  node_artpolicy["Artwork selection<br/>[ArtworkPolicy.cpp]"]
  node_enrichmentrules["BPM and lyrics rules<br/>[Enrichment.cpp]"]
  node_changeplan["Change plan rules<br/>[ChangePlan.cpp]"]
  node_naming["Naming template<br/>[NamingTemplate.cpp]"]
end

subgraph group_infrastructure["Storage and media"]
  node_sqlite[("SQLite catalogue<br/>[Sqlite.cpp]")]
  node_tagreader["Tag reader<br/>[TagReader.cpp]"]
  node_tagwriter["Tag writer<br/>[TagWriter.cpp]"]
  node_providers["Metadata providers<br/>[Providers.cpp]"]
  node_assetstore[("Artwork asset store<br/>[ImagePipeline.cpp]")]
  node_imagepipe["Image processing<br/>[ImagePipeline.cpp]"]
  node_pathguard["Safe output guard<br/>[PathGuard.cpp]"]
end

subgraph group_desktop["Desktop features"]
  node_mainwindow["Desktop workbench<br/>[MainWindow.cpp]"]
  node_albumreview["Artwork review"]
  node_player["Audio playback<br/>[AudioPlayer.cpp]"]
  node_spectrum["Spectrum analysis"]
end

node_user(("User"))
node_lrclib["LRCLIB service"]
node_sourcefiles[("Source music files")]
node_outputfiles[("Organised copies")]

node_user -->|"runs command"| node_cli
node_user -->|"opens library"| node_desktopapp
node_cli -->|"calls"| node_library
node_desktopapp -->|"opens window"| node_mainwindow
node_mainwindow -->|"runs operations"| node_library
node_library -->|"runs scan"| node_scan
node_scan -->|"reads tags"| node_sourcefiles
node_scan -->|"reads frames"| node_tagreader
node_scan -->|"records inventory"| node_catalogue
node_catalogue -->|"reads and writes"| node_sqlite
node_library -->|"groups albums"| node_albumgroup
node_library -->|"runs enrichment"| node_enrichment
node_enrichment -->|"loads and records"| node_catalogue
node_enrichment -->|"ranks artwork"| node_artpolicy
node_enrichment -->|"decides BPM and lyrics"| node_enrichmentrules
node_enrichment -->|"requests matches"| node_providers
node_providers -.->|"looks up lyrics"| node_lrclib
node_enrichment -->|"stores artwork"| node_assetstore
node_enrichment -->|"makes derivatives"| node_imagepipe
node_enrichment -->|"builds destinations"| node_naming
node_enrichment -->|"computes changes"| node_changeplan
node_enrichment -->|"guards output"| node_pathguard
node_enrichment -->|"writes copy tags"| node_tagwriter
node_enrichment -->|"copies audio payload"| node_sourcefiles
node_enrichment -->|"writes and verifies"| node_outputfiles
node_mainwindow -->|"shows artwork review"| node_albumreview
node_albumreview -->|"loads candidates"| node_assetstore
node_albumreview -->|"previews derivative"| node_imagepipe
node_mainwindow -->|"controls playback"| node_player
node_player -->|"plays track"| node_sourcefiles
node_mainwindow -->|"shows spectrum"| node_spectrum

click node_cli "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Cli/src/main.cpp"
click node_desktopapp "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/main.cpp"
click node_library "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/include/mlapp/Library.hpp"
click node_scan "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/Library.cpp"
click node_enrichment "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/LibraryEnrichment.cpp"
click node_catalogue "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/Catalogue.cpp"
click node_sqlite "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/Sqlite.cpp"
click node_tagreader "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/TagReader.cpp"
click node_tagwriter "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/TagWriter.cpp"
click node_albumgroup "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/AlbumGrouping.cpp"
click node_artpolicy "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/ArtworkPolicy.cpp"
click node_enrichmentrules "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/Enrichment.cpp"
click node_changeplan "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/ChangePlan.cpp"
click node_naming "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/NamingTemplate.cpp"
click node_providers "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/Providers.cpp"
click node_assetstore "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/ImagePipeline.cpp"
click node_imagepipe "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/ImagePipeline.cpp"
click node_pathguard "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/PathGuard.cpp"
click node_mainwindow "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/MainWindow.cpp"
click node_albumreview "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/AlbumReviewWidget.cpp"
click node_player "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/AudioPlayer.cpp"
click node_spectrum "https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/VfdSpectrumWidget.cpp"

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_cli,node_desktopapp,node_user toneBlue
class node_library,node_scan,node_enrichment,node_catalogue,node_sourcefiles,node_outputfiles toneAmber
class node_albumgroup,node_artpolicy,node_enrichmentrules,node_changeplan,node_naming toneMint
class node_sqlite,node_tagreader,node_tagwriter,node_providers,node_assetstore,node_imagepipe,node_pathguard toneRose
class node_mainwindow,node_albumreview,node_player,node_spectrum,node_lrclib toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Cli/src/main.cpp): `src/MusicLibrary.Cli/src/main.cpp`
- [Desktop app](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/main.cpp): `src/MusicLibrary.Desktop/src/main.cpp`

### Library workflow

- [Library engine](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/include/mlapp/Library.hpp): `src/MusicLibrary.Application/include/mlapp/Library.hpp`
- [Scan and catalogue](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/Library.cpp): `src/MusicLibrary.Application/src/Library.cpp`
- [Enrichment and export](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/LibraryEnrichment.cpp): `src/MusicLibrary.Application/src/LibraryEnrichment.cpp`
- [Catalogue repository](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Application/src/Catalogue.cpp): `src/MusicLibrary.Application/src/Catalogue.cpp`

### Domain decisions

- [Album grouping](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/AlbumGrouping.cpp): `src/MusicLibrary.Core/src/AlbumGrouping.cpp`
- [Artwork selection](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/ArtworkPolicy.cpp): `src/MusicLibrary.Core/src/ArtworkPolicy.cpp`
- [BPM and lyrics rules](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/Enrichment.cpp): `src/MusicLibrary.Core/src/Enrichment.cpp`
- [Change plan rules](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/ChangePlan.cpp): `src/MusicLibrary.Core/src/ChangePlan.cpp`
- [Naming template](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Core/src/NamingTemplate.cpp): `src/MusicLibrary.Core/src/NamingTemplate.cpp`

### Storage and media

- [SQLite catalogue](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/Sqlite.cpp): `src/MusicLibrary.Infrastructure/src/Sqlite.cpp`
- [Tag reader](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/TagReader.cpp): `src/MusicLibrary.Infrastructure/src/TagReader.cpp`
- [Tag writer](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/TagWriter.cpp): `src/MusicLibrary.Infrastructure/src/TagWriter.cpp`
- [Metadata providers](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/Providers.cpp): `src/MusicLibrary.Infrastructure/src/Providers.cpp`
- [Artwork asset store](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/ImagePipeline.cpp): `src/MusicLibrary.Infrastructure/src/ImagePipeline.cpp`
- [Image processing](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/ImagePipeline.cpp): `src/MusicLibrary.Infrastructure/src/ImagePipeline.cpp`
- [Safe output guard](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Infrastructure/src/PathGuard.cpp): `src/MusicLibrary.Infrastructure/src/PathGuard.cpp`

### Desktop features

- [Desktop workbench](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/MainWindow.cpp): `src/MusicLibrary.Desktop/src/MainWindow.cpp`
- [Artwork review](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/AlbumReviewWidget.cpp): `src/MusicLibrary.Desktop/src/AlbumReviewWidget.cpp`
- [Audio playback](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/AudioPlayer.cpp): `src/MusicLibrary.Desktop/src/AudioPlayer.cpp`
- [Spectrum analysis](https://github.com/blueangelcpt/resonance/blob/main/src/MusicLibrary.Desktop/src/VfdSpectrumWidget.cpp): `src/MusicLibrary.Desktop/src/VfdSpectrumWidget.cpp`

### Other components

- **User**
- **LRCLIB service**
- **Source music files**
- **Organised copies**

## Connections

- User → CLI commands: runs command
- User → Desktop app: opens library
- CLI commands → Library engine: calls
- Desktop app → Desktop workbench: opens window
- Desktop workbench → Library engine: runs operations
- Library engine → Scan and catalogue: runs scan
- Scan and catalogue → Source music files: reads tags
- Scan and catalogue → Tag reader: reads frames
- Scan and catalogue → Catalogue repository: records inventory
- Catalogue repository → SQLite catalogue: reads and writes
- Library engine → Album grouping: groups albums
- Library engine → Enrichment and export: runs enrichment
- Enrichment and export → Catalogue repository: loads and records
- Enrichment and export → Artwork selection: ranks artwork
- Enrichment and export → BPM and lyrics rules: decides BPM and lyrics
- Enrichment and export → Metadata providers: requests matches
- Metadata providers → LRCLIB service: looks up lyrics
- Enrichment and export → Artwork asset store: stores artwork
- Enrichment and export → Image processing: makes derivatives
- Enrichment and export → Naming template: builds destinations
- Enrichment and export → Change plan rules: computes changes
- Enrichment and export → Safe output guard: guards output
- Enrichment and export → Tag writer: writes copy tags
- Enrichment and export → Source music files: copies audio payload
- Enrichment and export → Organised copies: writes and verifies
- Desktop workbench → Artwork review: shows artwork review
- Artwork review → Artwork asset store: loads candidates
- Artwork review → Image processing: previews derivative
- Desktop workbench → Audio playback: controls playback
- Audio playback → Source music files: plays track
- Desktop workbench → Spectrum analysis: shows spectrum