# itheroken/lunera architecture

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

- Interactive diagram: https://gitdiagram.com/itheroken/lunera
- Repository: https://github.com/itheroken/lunera

## Overview

This repository appears to be an Electron music player. Its central workflow is desktop playback: the app coordinates audio extraction and streaming through two engine families, with yt-dlp as a resolution backend. Separate service branches cover playlist transfer and matching, audio scenes, game overlays, and updates. The README is empty, and the excerpts do not show most IPC handlers or UI wiring; dashed links mark likely integration points that cannot be verified from the sampled calls.

Main entry points: [`main.js`](https://github.com/itheroken/lunera/blob/main/main.js) (Electron app), [`services/lse/core/StreamEngine.js`](https://github.com/itheroken/lunera/blob/main/services/lse/core/StreamEngine.js) (LSE engine), [`services/lte/core/TurboEngine.js`](https://github.com/itheroken/lunera/blob/main/services/lte/core/TurboEngine.js) (LTE engine), [`services/audioExtractor.js`](https://github.com/itheroken/lunera/blob/main/services/audioExtractor.js) (Audio extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop app"]
  node_desktop["Electron app<br/>[main.js]"]
end

subgraph group_playback["Audio playback"]
  node_audio["Audio extraction<br/>[audioExtractor.js]"]
  node_lse["LSE engine<br/>[StreamEngine.js]"]
  node_lseconfig["LSE settings<br/>[defaultSettings.js]"]
  node_lsenetwork["Network manager<br/>[NetworkManager.js]"]
  node_lsecache[("Metadata cache<br/>[MetadataCache.js]")]
  node_lseregistry["Extractor registry"]
  node_localextract["Local extractor<br/>[LocalExtractor.js]"]
  node_directextract["Direct media"]
  node_hls["HLS extractor<br/>[HLSExtractor.js]"]
  node_dash["DASH extractor<br/>[DASHExtractor.js]"]
  node_turbo["LTE engine<br/>[TurboEngine.js]"]
  node_ltequeue["Extraction queue<br/>[ExtractionQueue.js]"]
  node_ltecache[("Turbo cache<br/>[ExtractionCache.js]")]
  node_lteformat["Format selector<br/>[FormatSelector.js]"]
  node_ytdlpmanager["yt-dlp manager<br/>[YtDlpManager.js]"]
  node_streammanager["Stream manager<br/>[StreamManager.js]"]
  node_ytdlp["yt-dlp service<br/>[ytdlpService.js]"]
end

subgraph group_integrations["Music services"]
  node_playlist["Playlist transfer"]
  node_spotifymatch["Spotify matching<br/>[spotifyMatch.js]"]
  node_publiccollection["Public collections"]
  node_importdialog["Import dialog<br/>[importDialog.js]"]
end

subgraph group_experience["Player features"]
  node_audio_scene["Audio scenes<br/>[audioScene.js]"]
  node_original_scene["Original scenes"]
  node_gameoverlay["Game overlay<br/>[gameOverlay.js]"]
  node_updater["App updater<br/>[appUpdater.js]"]
end

node_user(("Listener"))

node_user -.->|"uses"| node_desktop
node_desktop -.->|"routes playback"| node_audio
node_desktop -.->|"integrates"| node_lse
node_desktop -.->|"integrates"| node_turbo
node_desktop -.->|"integrates"| node_playlist
node_desktop -.->|"integrates"| node_publiccollection
node_desktop -.->|"creates overlay"| node_gameoverlay
node_desktop -.->|"starts updater"| node_updater
node_audio -.->|"uses"| node_lse
node_audio -.->|"uses"| node_turbo
node_lse -->|"normalizes settings"| node_lseconfig
node_lse -->|"reads and writes"| node_lsecache
node_lse -->|"uses network"| node_lsenetwork
node_lse -->|"dispatches extractors"| node_lseregistry
node_lse -->|"registers extractor"| node_localextract
node_lse -->|"registers extractor"| node_directextract
node_lse -->|"registers extractor"| node_hls
node_lse -->|"registers extractor"| node_dash
node_turbo -->|"uses cache"| node_ltecache
node_turbo -->|"queues extraction"| node_ltequeue
node_turbo -->|"selects format"| node_lteformat
node_turbo -->|"resolves media"| node_ytdlpmanager
node_turbo -.->|"manages streams"| node_streammanager
node_ytdlpmanager -->|"delegates resolution"| node_ytdlp
node_playlist -->|"matches tracks"| node_spotifymatch
node_desktop -.->|"integrates"| node_importdialog
node_desktop -.->|"integrates"| node_audio_scene
node_desktop -.->|"integrates"| node_original_scene

click node_desktop "https://github.com/itheroken/lunera/blob/main/main.js"
click node_audio "https://github.com/itheroken/lunera/blob/main/services/audioExtractor.js"
click node_lse "https://github.com/itheroken/lunera/blob/main/services/lse/core/StreamEngine.js"
click node_lseconfig "https://github.com/itheroken/lunera/blob/main/services/lse/config/defaultSettings.js"
click node_lsenetwork "https://github.com/itheroken/lunera/blob/main/services/lse/core/NetworkManager.js"
click node_lsecache "https://github.com/itheroken/lunera/blob/main/services/lse/cache/MetadataCache.js"
click node_lseregistry "https://github.com/itheroken/lunera/blob/main/services/lse/extractors/ProviderRegistry.js"
click node_localextract "https://github.com/itheroken/lunera/blob/main/services/lse/extractors/LocalExtractor.js"
click node_directextract "https://github.com/itheroken/lunera/blob/main/services/lse/extractors/DirectMediaExtractor.js"
click node_hls "https://github.com/itheroken/lunera/blob/main/services/lse/extractors/HLSExtractor.js"
click node_dash "https://github.com/itheroken/lunera/blob/main/services/lse/extractors/DASHExtractor.js"
click node_turbo "https://github.com/itheroken/lunera/blob/main/services/lte/core/TurboEngine.js"
click node_ltequeue "https://github.com/itheroken/lunera/blob/main/services/lte/extraction/ExtractionQueue.js"
click node_ltecache "https://github.com/itheroken/lunera/blob/main/services/lte/extraction/ExtractionCache.js"
click node_lteformat "https://github.com/itheroken/lunera/blob/main/services/lte/extraction/FormatSelector.js"
click node_ytdlpmanager "https://github.com/itheroken/lunera/blob/main/services/lte/extraction/YtDlpManager.js"
click node_streammanager "https://github.com/itheroken/lunera/blob/main/services/lte/streaming/StreamManager.js"
click node_ytdlp "https://github.com/itheroken/lunera/blob/main/services/ytdlpService.js"
click node_playlist "https://github.com/itheroken/lunera/blob/main/services/playlistTransfer.js"
click node_spotifymatch "https://github.com/itheroken/lunera/blob/main/services/spotifyMatch.js"
click node_publiccollection "https://github.com/itheroken/lunera/blob/main/services/publicCollection.js"
click node_audio_scene "https://github.com/itheroken/lunera/blob/main/services/audioScene.js"
click node_original_scene "https://github.com/itheroken/lunera/blob/main/services/originalAudioScene.js"
click node_gameoverlay "https://github.com/itheroken/lunera/blob/main/services/gameOverlay.js"
click node_updater "https://github.com/itheroken/lunera/blob/main/services/appUpdater.js"
click node_importdialog "https://github.com/itheroken/lunera/blob/main/services/importDialog.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_desktop toneBlue
class node_audio,node_lse,node_lseconfig,node_lsenetwork,node_lsecache,node_lseregistry,node_localextract,node_directextract,node_hls,node_dash,node_turbo,node_ltequeue,node_ltecache,node_lteformat,node_ytdlpmanager,node_streammanager,node_ytdlp toneAmber
class node_playlist,node_spotifymatch,node_publiccollection,node_importdialog toneMint
class node_audio_scene,node_original_scene,node_gameoverlay,node_updater toneRose
class node_user toneIndigo
```

## Components

### Desktop app

- [Electron app](https://github.com/itheroken/lunera/blob/main/main.js): `main.js`

### Audio playback

- [Audio extraction](https://github.com/itheroken/lunera/blob/main/services/audioExtractor.js): `services/audioExtractor.js`
- [LSE engine](https://github.com/itheroken/lunera/blob/main/services/lse/core/StreamEngine.js): `services/lse/core/StreamEngine.js`
- [LSE settings](https://github.com/itheroken/lunera/blob/main/services/lse/config/defaultSettings.js): `services/lse/config/defaultSettings.js`
- [Network manager](https://github.com/itheroken/lunera/blob/main/services/lse/core/NetworkManager.js): `services/lse/core/NetworkManager.js`
- [Metadata cache](https://github.com/itheroken/lunera/blob/main/services/lse/cache/MetadataCache.js): `services/lse/cache/MetadataCache.js`
- [Extractor registry](https://github.com/itheroken/lunera/blob/main/services/lse/extractors/ProviderRegistry.js): `services/lse/extractors/ProviderRegistry.js`
- [Local extractor](https://github.com/itheroken/lunera/blob/main/services/lse/extractors/LocalExtractor.js): `services/lse/extractors/LocalExtractor.js`
- [Direct media](https://github.com/itheroken/lunera/blob/main/services/lse/extractors/DirectMediaExtractor.js): `services/lse/extractors/DirectMediaExtractor.js`
- [HLS extractor](https://github.com/itheroken/lunera/blob/main/services/lse/extractors/HLSExtractor.js): `services/lse/extractors/HLSExtractor.js`
- [DASH extractor](https://github.com/itheroken/lunera/blob/main/services/lse/extractors/DASHExtractor.js): `services/lse/extractors/DASHExtractor.js`
- [LTE engine](https://github.com/itheroken/lunera/blob/main/services/lte/core/TurboEngine.js): `services/lte/core/TurboEngine.js`
- [Extraction queue](https://github.com/itheroken/lunera/blob/main/services/lte/extraction/ExtractionQueue.js): `services/lte/extraction/ExtractionQueue.js`
- [Turbo cache](https://github.com/itheroken/lunera/blob/main/services/lte/extraction/ExtractionCache.js): `services/lte/extraction/ExtractionCache.js`
- [Format selector](https://github.com/itheroken/lunera/blob/main/services/lte/extraction/FormatSelector.js): `services/lte/extraction/FormatSelector.js`
- [yt-dlp manager](https://github.com/itheroken/lunera/blob/main/services/lte/extraction/YtDlpManager.js): `services/lte/extraction/YtDlpManager.js`
- [Stream manager](https://github.com/itheroken/lunera/blob/main/services/lte/streaming/StreamManager.js): `services/lte/streaming/StreamManager.js`
- [yt-dlp service](https://github.com/itheroken/lunera/blob/main/services/ytdlpService.js): `services/ytdlpService.js`

### Music services

- [Playlist transfer](https://github.com/itheroken/lunera/blob/main/services/playlistTransfer.js): `services/playlistTransfer.js`
- [Spotify matching](https://github.com/itheroken/lunera/blob/main/services/spotifyMatch.js): `services/spotifyMatch.js`
- [Public collections](https://github.com/itheroken/lunera/blob/main/services/publicCollection.js): `services/publicCollection.js`
- [Import dialog](https://github.com/itheroken/lunera/blob/main/services/importDialog.js): `services/importDialog.js`

### Player features

- [Audio scenes](https://github.com/itheroken/lunera/blob/main/services/audioScene.js): `services/audioScene.js`
- [Original scenes](https://github.com/itheroken/lunera/blob/main/services/originalAudioScene.js): `services/originalAudioScene.js`
- [Game overlay](https://github.com/itheroken/lunera/blob/main/services/gameOverlay.js): `services/gameOverlay.js`
- [App updater](https://github.com/itheroken/lunera/blob/main/services/appUpdater.js): `services/appUpdater.js`

### Other components

- **Listener**

## Connections

- Listener → Electron app: uses
- Electron app → Audio extraction: routes playback (evidence: `main.js`)
- Electron app → LSE engine: integrates
- Electron app → LTE engine: integrates
- Electron app → Playlist transfer: integrates
- Electron app → Public collections: integrates (evidence: `main.js`)
- Electron app → Game overlay: creates overlay (evidence: `main.js`)
- Electron app → App updater: starts updater (evidence: `main.js`)
- Audio extraction → LSE engine: uses
- Audio extraction → LTE engine: uses
- LSE engine → LSE settings: normalizes settings (evidence: `services/lse/core/StreamEngine.js`)
- LSE engine → Metadata cache: reads and writes (evidence: `services/lse/core/StreamEngine.js`)
- LSE engine → Network manager: uses network (evidence: `services/lse/core/StreamEngine.js`)
- LSE engine → Extractor registry: dispatches extractors (evidence: `services/lse/core/StreamEngine.js`)
- LSE engine → Local extractor: registers extractor (evidence: `services/lse/core/StreamEngine.js`)
- LSE engine → Direct media: registers extractor (evidence: `services/lse/core/StreamEngine.js`)
- LSE engine → HLS extractor: registers extractor (evidence: `services/lse/core/StreamEngine.js`)
- LSE engine → DASH extractor: registers extractor (evidence: `services/lse/core/StreamEngine.js`)
- LTE engine → Turbo cache: uses cache (evidence: `services/lte/core/TurboEngine.js`)
- LTE engine → Extraction queue: queues extraction (evidence: `services/lte/core/TurboEngine.js`)
- LTE engine → Format selector: selects format (evidence: `services/lte/core/TurboEngine.js`)
- LTE engine → yt-dlp manager: resolves media (evidence: `services/lte/core/TurboEngine.js`)
- LTE engine → Stream manager: manages streams (evidence: `services/lte/core/TurboEngine.js`)
- yt-dlp manager → yt-dlp service: delegates resolution (evidence: `services/lte/extraction/YtDlpManager.js`)
- Playlist transfer → Spotify matching: matches tracks (evidence: `services/playlistTransfer.js`)
- Electron app → Import dialog: integrates
- Electron app → Audio scenes: integrates
- Electron app → Original scenes: integrates
