# darshanseenivasakumar/theaestheticslyrics architecture

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

- Interactive diagram: https://gitdiagram.com/darshanseenivasakumar/theaestheticslyrics
- Repository: https://github.com/darshanseenivasakumar/theaestheticslyrics

## Overview

theaestheticslyrics is a Windows tray app that follows media playback and displays word-synchronized lyrics in a full-screen screen or desktop overlay. Its main workflow runs from media-session detection through local/cache and online lyric lookup, timing preparation, and stage rendering; settings, tray controls, and album-art colour sync support that flow. The graph includes documented capabilities whose implementation was not sampled; dashed edges with null evidence indicate relationships not verified in the excerpts.

Main entry points: [`src/main/app-controller.ts`](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/app-controller.ts) (App controller), [`src/main/lyrics/service.ts`](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/service.ts) (Lyrics service), [`src/renderer/src/stage/main.ts`](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/renderer/src/stage/main.ts) (Stage renderer), [`src/main/media/watcher.ts`](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/media/watcher.ts) (Media watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_app["App controller<br/>[app-controller.ts]"]
  node_entry["Electron entry<br/>[index.ts]"]
end

subgraph group_playback["Playback tracking"]
  node_watcher["Media watcher<br/>[watcher.ts]"]
  node_media["Windows media sessions"]
end

subgraph group_lyrics["Lyrics retrieval"]
  node_lyricsvc["Lyrics service<br/>[service.ts]"]
  node_local["Local lyrics<br/>[local.ts]"]
  node_cache[("Lyrics cache<br/>[cache.ts]")]
  node_lrclib["LRCLIB client<br/>[lrclib.ts]"]
  node_netease["NetEase client<br/>[netease.ts]"]
  node_lyricsfiles["Lyrics sources"]
  node_lrclibservice["LRCLIB service"]
  node_neteaseservice["NetEase service"]
end

subgraph group_presentation["Lyrics presentation"]
  node_stagecontroller["Stage controller"]
  node_renderer["Stage renderer<br/>[main.ts]"]
  node_model["Lyrics model<br/>[model.ts]"]
  node_styles["Display styles"]
  node_overlay["Screen or overlay"]
end

subgraph group_preferences["Settings and colour"]
  node_settings[("Settings store<br/>[settings.ts]")]
  node_tray["Tray menu<br/>[tray.ts]"]
  node_colors["Album-art palette<br/>[extract.ts]"]
end

node_user(("User"))
node_spotify["Spotify or Apple Music"]

node_entry -->|"starts"| node_app
node_app -->|"creates"| node_settings
node_app -->|"creates"| node_watcher
node_app -->|"creates"| node_lyricsvc
node_app -->|"creates"| node_tray
node_watcher -->|"reads sessions"| node_media
node_spotify -->|"publishes playback"| node_media
node_watcher -.->|"emits track"| node_app
node_app -->|"looks up lyrics"| node_lyricsvc
node_lyricsvc -->|"checks files"| node_local
node_lyricsvc -->|"checks cache"| node_cache
node_lyricsvc -->|"fetches lyrics"| node_lrclib
node_lyricsvc -->|"fetches word timing"| node_netease
node_local -.->|"parses files"| node_lyricsfiles
node_lrclib -->|"queries"| node_lrclibservice
node_netease -.->|"queries"| node_neteaseservice
node_user -->|"sets options"| node_tray
node_tray -->|"updates"| node_settings
node_app -->|"controls display"| node_stagecontroller
node_stagecontroller -->|"loads stage"| node_renderer
node_renderer -->|"builds model"| node_model
node_renderer -->|"selects style"| node_styles
node_stagecontroller -->|"shows lyrics"| node_overlay
node_renderer -->|"renders words"| node_overlay
node_app -->|"extracts palette"| node_colors
node_colors -->|"updates colours"| node_settings

click node_app "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/app-controller.ts"
click node_entry "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/index.ts"
click node_settings "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/settings.ts"
click node_tray "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/ui/tray.ts"
click node_watcher "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/media/watcher.ts"
click node_lyricsvc "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/service.ts"
click node_local "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/local.ts"
click node_cache "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/cache.ts"
click node_lrclib "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/lrclib.ts"
click node_netease "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/netease.ts"
click node_lyricsfiles "https://github.com/darshanseenivasakumar/theaestheticslyrics/tree/main/src/main/lyrics"
click node_stagecontroller "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/ui/stage-controller.ts"
click node_renderer "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/renderer/src/stage/main.ts"
click node_model "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/renderer/src/stage/model.ts"
click node_styles "https://github.com/darshanseenivasakumar/theaestheticslyrics/tree/main/src/renderer/src/stage/styles"
click node_colors "https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/palette/extract.ts"

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_entry,node_user toneBlue
class node_watcher,node_media toneAmber
class node_lyricsvc,node_local,node_cache,node_lrclib,node_netease,node_lyricsfiles,node_lrclibservice,node_neteaseservice toneMint
class node_stagecontroller,node_renderer,node_model,node_styles,node_overlay toneRose
class node_settings,node_tray,node_colors,node_spotify toneIndigo
```

## Components

### App runtime

- [App controller](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/app-controller.ts): `src/main/app-controller.ts`
- [Electron entry](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/index.ts): `src/main/index.ts`

### Playback tracking

- [Media watcher](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/media/watcher.ts): `src/main/media/watcher.ts`
- **Windows media sessions**

### Lyrics retrieval

- [Lyrics service](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/service.ts): `src/main/lyrics/service.ts`
- [Local lyrics](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/local.ts): `src/main/lyrics/local.ts`
- [Lyrics cache](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/cache.ts): `src/main/lyrics/cache.ts`
- [LRCLIB client](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/lrclib.ts): `src/main/lyrics/lrclib.ts`
- [NetEase client](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/lyrics/netease.ts): `src/main/lyrics/netease.ts`
- [Lyrics sources](https://github.com/darshanseenivasakumar/theaestheticslyrics/tree/main/src/main/lyrics): `src/main/lyrics`
- **LRCLIB service**
- **NetEase service**

### Lyrics presentation

- [Stage controller](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/ui/stage-controller.ts): `src/main/ui/stage-controller.ts`
- [Stage renderer](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/renderer/src/stage/main.ts): `src/renderer/src/stage/main.ts`
- [Lyrics model](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/renderer/src/stage/model.ts): `src/renderer/src/stage/model.ts`
- [Display styles](https://github.com/darshanseenivasakumar/theaestheticslyrics/tree/main/src/renderer/src/stage/styles): `src/renderer/src/stage/styles`
- **Screen or overlay**

### Settings and colour

- [Settings store](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/settings.ts): `src/main/settings.ts`
- [Tray menu](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/ui/tray.ts): `src/main/ui/tray.ts`
- [Album-art palette](https://github.com/darshanseenivasakumar/theaestheticslyrics/blob/main/src/main/palette/extract.ts): `src/main/palette/extract.ts`

### Other components

- **User**
- **Spotify or Apple Music**

## Connections

- Electron entry → App controller: starts (evidence: `src/main/index.ts`)
- App controller → Settings store: creates (evidence: `src/main/app-controller.ts`)
- App controller → Media watcher: creates (evidence: `src/main/app-controller.ts`)
- App controller → Lyrics service: creates (evidence: `src/main/app-controller.ts`)
- App controller → Tray menu: creates (evidence: `src/main/app-controller.ts`)
- Media watcher → Windows media sessions: reads sessions (evidence: `src/main/media/watcher.ts`)
- Spotify or Apple Music → Windows media sessions: publishes playback (evidence: `README.md`)
- Media watcher → App controller: emits track (evidence: `src/main/app-controller.ts`)
- App controller → Lyrics service: looks up lyrics (evidence: `src/main/app-controller.ts`)
- Lyrics service → Local lyrics: checks files (evidence: `src/main/lyrics/service.ts`)
- Lyrics service → Lyrics cache: checks cache (evidence: `src/main/lyrics/service.ts`)
- Lyrics service → LRCLIB client: fetches lyrics (evidence: `src/main/lyrics/service.ts`)
- Lyrics service → NetEase client: fetches word timing (evidence: `src/main/lyrics/service.ts`)
- Local lyrics → Lyrics sources: parses files (evidence: `src/main/lyrics/local.ts`)
- LRCLIB client → LRCLIB service: queries (evidence: `src/main/lyrics/lrclib.ts`)
- NetEase client → NetEase service: queries
- User → Tray menu: sets options (evidence: `README.md`)
- Tray menu → Settings store: updates (evidence: `src/main/ui/tray.ts`)
- App controller → Stage controller: controls display (evidence: `src/main/app-controller.ts`)
- Stage controller → Stage renderer: loads stage (evidence: `src/main/ui/stage-controller.ts`)
- Stage renderer → Lyrics model: builds model (evidence: `src/renderer/src/stage/main.ts`)
- Stage renderer → Display styles: selects style (evidence: `src/renderer/src/stage/main.ts`)
- Stage controller → Screen or overlay: shows lyrics (evidence: `README.md`)
- Stage renderer → Screen or overlay: renders words (evidence: `README.md`)
- App controller → Album-art palette: extracts palette (evidence: `src/main/app-controller.ts`)
- Album-art palette → Settings store: updates colours (evidence: `src/main/app-controller.ts`)
