# gort-trindade/sonar-music-player architecture

> Architecture diagram of the GitHub repository gort-trindade/sonar-music-player, 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/gort-trindade/sonar-music-player
- Repository: https://github.com/gort-trindade/sonar-music-player
- Video tour (about a minute): https://gitdiagram.com/gort-trindade/sonar-music-player/video

## Overview

Sonar is an Electron desktop player for browsing and listening to local music. The user chooses a player layout in the launcher, then uses the renderer to organize a library, select tracks, and play them with audio customization; lyrics and cover-driven visuals enrich playback. Electron’s main process creates windows and handles file metadata and FLAC decoding, with a preload bridge exposing selected capabilities to renderer code. The README also documents themes, layouts, and Last.fm scrobbling. Those features are represented from documentation and the tree; their detailed wiring is not established by the sampled excerpts.

Main entry points: [`renderer/js/index.js`](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js) (Player renderer), [`main.js`](https://github.com/gort-trindade/sonar-music-player/blob/main/main.js) (Electron main), [`preload.js`](https://github.com/gort-trindade/sonar-music-player/blob/main/preload.js) (Preload bridge), [`renderer/js/launcher.js`](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/launcher.js) (Layout launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Electron app"]
  node_launcher["Layout launcher<br/>[launcher.js]"]
  node_main["Electron main<br/>[main.js]"]
  node_bridge["Preload bridge<br/>[preload.js]"]
end

subgraph group_library["Library and playback"]
  node_player["Player renderer<br/>[index.js]"]
  node_libraryui["Library organization<br/>[index.js]"]
  node_metadata["Track metadata<br/>[main.js]"]
  node_audio["Playback and effects<br/>[index.js]"]
  node_flac["FLAC decoder<br/>[flac-worker.js]"]
  node_cache[("PCM audio cache<br/>[main.js]")]
end

subgraph group_presentation["Playback presentation"]
  node_lyrics["Synchronized lyrics<br/>[index.js]"]
  node_visuals["Covers and visualizer<br/>[index.js]"]
  node_appearance["Layouts and themes<br/>[index.js]"]
end

subgraph group_integration["External integration"]
  node_lastfm["Last.fm scrobbling<br/>[index.js]"]
end

node_user(("Listener"))
node_localfiles["Local music files"]
node_lastfmservice(("Last.fm service"))

node_user -->|"chooses layout"| node_launcher
node_launcher -->|"launches player"| node_bridge
node_bridge -->|"sends IPC"| node_main
node_main -->|"loads window"| node_player
node_user -->|"controls playback"| node_player
node_player -->|"requests file services"| node_bridge
node_bridge -->|"forwards requests"| node_main
node_main -->|"reads files"| node_localfiles
node_main -->|"parses tags"| node_metadata
node_main -->|"dispatches decode"| node_flac
node_flac -->|"returns PCM"| node_main
node_main -->|"reads and writes"| node_cache
node_player -->|"organizes library"| node_libraryui
node_player -->|"plays and processes"| node_audio
node_player -->|"renders lyrics"| node_lyrics
node_player -->|"renders visuals"| node_visuals
node_player -->|"applies appearance"| node_appearance
node_player -.->|"scrobbles tracks"| node_lastfm
node_lastfm -.->|"sends scrobbles"| node_lastfmservice

click node_launcher "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/launcher.js"
click node_main "https://github.com/gort-trindade/sonar-music-player/blob/main/main.js"
click node_bridge "https://github.com/gort-trindade/sonar-music-player/blob/main/preload.js"
click node_player "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js"
click node_libraryui "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js"
click node_metadata "https://github.com/gort-trindade/sonar-music-player/blob/main/main.js"
click node_audio "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js"
click node_flac "https://github.com/gort-trindade/sonar-music-player/blob/main/flac-worker.js"
click node_cache "https://github.com/gort-trindade/sonar-music-player/blob/main/main.js"
click node_lyrics "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js"
click node_visuals "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js"
click node_appearance "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js"
click node_lastfm "https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js"

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_launcher,node_main,node_bridge toneBlue
class node_player,node_libraryui,node_metadata,node_audio,node_flac,node_cache toneAmber
class node_lyrics,node_visuals,node_appearance toneMint
class node_lastfm toneRose
class node_user,node_localfiles,node_lastfmservice toneIndigo
```

## Components

### Electron app

- [Layout launcher](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/launcher.js): `renderer/js/launcher.js`
- [Electron main](https://github.com/gort-trindade/sonar-music-player/blob/main/main.js): `main.js`
- [Preload bridge](https://github.com/gort-trindade/sonar-music-player/blob/main/preload.js): `preload.js`

### Library and playback

- [Player renderer](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js): `renderer/js/index.js`
- [Library organization](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js): `renderer/js/index.js`
- [Track metadata](https://github.com/gort-trindade/sonar-music-player/blob/main/main.js): `main.js`
- [Playback and effects](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js): `renderer/js/index.js`
- [FLAC decoder](https://github.com/gort-trindade/sonar-music-player/blob/main/flac-worker.js): `flac-worker.js`
- [PCM audio cache](https://github.com/gort-trindade/sonar-music-player/blob/main/main.js): `main.js`

### Playback presentation

- [Synchronized lyrics](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js): `renderer/js/index.js`
- [Covers and visualizer](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js): `renderer/js/index.js`
- [Layouts and themes](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js): `renderer/js/index.js`

### External integration

- [Last.fm scrobbling](https://github.com/gort-trindade/sonar-music-player/blob/main/renderer/js/index.js): `renderer/js/index.js`

### Other components

- **Listener**
- **Local music files**
- **Last.fm service**

## Connections

- Listener → Layout launcher: chooses layout
- Layout launcher → Preload bridge: launches player
- Preload bridge → Electron main: sends IPC
- Electron main → Player renderer: loads window
- Listener → Player renderer: controls playback
- Player renderer → Preload bridge: requests file services
- Preload bridge → Electron main: forwards requests
- Electron main → Local music files: reads files
- Electron main → Track metadata: parses tags
- Electron main → FLAC decoder: dispatches decode
- FLAC decoder → Electron main: returns PCM
- Electron main → PCM audio cache: reads and writes
- Player renderer → Library organization: organizes library
- Player renderer → Playback and effects: plays and processes
- Player renderer → Synchronized lyrics: renders lyrics
- Player renderer → Covers and visualizer: renders visuals
- Player renderer → Layouts and themes: applies appearance
- Player renderer → Last.fm scrobbling: scrobbles tracks
- Last.fm scrobbling → Last.fm service: sends scrobbles