# sushant-demn/sustify architecture

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

- Interactive diagram: https://gitdiagram.com/sushant-demn/sustify
- Repository: https://github.com/sushant-demn/sustify

## Overview

Sustify is a local desktop audio player: the user opens the native WebView UI, selects audio, and the C++ backend adds tracks to a queue and starts playback; UI-bound calls expose playback and queue controls. The backend separates WebView startup and bindings, file selection, queue/metadata handling, and audio playback. The README also documents ID3 metadata extraction. The GUI script and large miniaudio header were not excerpted, so GUI-to-bridge wiring is shown as unverified; other links reflect shown calls or documented capabilities.

Main entry points: [`src/bindings.cpp`](https://github.com/sushant-demn/sustify/blob/master/src/bindings.cpp) (WebView Bindings), [`src/window.cpp`](https://github.com/sushant-demn/sustify/blob/master/src/window.cpp) (WebView Host), [`gui/index.html`](https://github.com/sushant-demn/sustify/blob/master/gui/index.html) (UI Document), [`src/audio.cpp`](https://github.com/sushant-demn/sustify/blob/master/src/audio.cpp) (Audio Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web UI"]
  node_ui_shell["UI Document<br/>[index.html]"]
  node_ui_script["UI Controls<br/>[index.js]"]
  node_ui_style["UI Styling<br/>[index.css]"]
end

subgraph group_host["Desktop Bridge"]
  node_window["WebView Host<br/>[window.cpp]"]
  node_bindings["WebView Bindings<br/>[bindings.cpp]"]
end

subgraph group_library["Track Library"]
  node_filesystem["File Selection<br/>[file_system.cpp]"]
  node_file_dialogs["File Dialogs"]
  node_queue[("Track Queue<br/>[queue.cpp]")]
  node_queue_api["Queue API<br/>[queue.h]"]
end

subgraph group_playback["Audio Playback"]
  node_audio["Audio Engine<br/>[audio.cpp]"]
  node_audio_api["Audio API<br/>[audio.h]"]
  node_miniaudio["Miniaudio Runtime<br/>[miniaudio.h]"]
end

node_user(("Listener"))
node_webview["Native WebView"]
node_taglib["TagLib"]

node_user -->|"uses"| node_ui_shell
node_window -->|"loads"| node_ui_shell
node_window -->|"creates and runs"| node_webview
node_window -->|"registers"| node_bindings
node_window -->|"initializes"| node_audio
node_ui_script -.->|"invokes bridge"| node_bindings
node_bindings -->|"selects file"| node_filesystem
node_filesystem -->|"opens dialog"| node_file_dialogs
node_bindings -->|"dispatches controls"| node_queue
node_bindings -->|"controls playback"| node_audio
node_queue -->|"starts and seeks"| node_audio
node_queue -->|"reads metadata"| node_taglib
node_audio -->|"uses engine"| node_miniaudio
node_ui_shell -.->|"loads"| node_ui_script
node_ui_shell -.->|"styles with"| node_ui_style

click node_ui_shell "https://github.com/sushant-demn/sustify/blob/master/gui/index.html"
click node_ui_script "https://github.com/sushant-demn/sustify/blob/master/gui/index.js"
click node_ui_style "https://github.com/sushant-demn/sustify/blob/master/gui/index.css"
click node_window "https://github.com/sushant-demn/sustify/blob/master/src/window.cpp"
click node_bindings "https://github.com/sushant-demn/sustify/blob/master/src/bindings.cpp"
click node_filesystem "https://github.com/sushant-demn/sustify/blob/master/src/file_system.cpp"
click node_file_dialogs "https://github.com/sushant-demn/sustify/blob/master/include/portable-file-dialogs.h"
click node_queue "https://github.com/sushant-demn/sustify/blob/master/src/queue.cpp"
click node_queue_api "https://github.com/sushant-demn/sustify/blob/master/headers/queue.h"
click node_audio "https://github.com/sushant-demn/sustify/blob/master/src/audio.cpp"
click node_audio_api "https://github.com/sushant-demn/sustify/blob/master/headers/audio.h"
click node_miniaudio "https://github.com/sushant-demn/sustify/blob/master/include/miniaudio.h"

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_ui_shell,node_ui_script,node_ui_style,node_webview toneBlue
class node_window,node_bindings toneAmber
class node_filesystem,node_file_dialogs,node_queue,node_queue_api toneMint
class node_audio,node_audio_api,node_miniaudio toneRose
class node_user,node_taglib toneIndigo
```

## Components

### Web UI

- [UI Document](https://github.com/sushant-demn/sustify/blob/master/gui/index.html): `gui/index.html`
- [UI Controls](https://github.com/sushant-demn/sustify/blob/master/gui/index.js): `gui/index.js`
- [UI Styling](https://github.com/sushant-demn/sustify/blob/master/gui/index.css): `gui/index.css`

### Desktop Bridge

- [WebView Host](https://github.com/sushant-demn/sustify/blob/master/src/window.cpp): `src/window.cpp`
- [WebView Bindings](https://github.com/sushant-demn/sustify/blob/master/src/bindings.cpp): `src/bindings.cpp`

### Track Library

- [File Selection](https://github.com/sushant-demn/sustify/blob/master/src/file_system.cpp): `src/file_system.cpp`
- [File Dialogs](https://github.com/sushant-demn/sustify/blob/master/include/portable-file-dialogs.h): `include/portable-file-dialogs.h`
- [Track Queue](https://github.com/sushant-demn/sustify/blob/master/src/queue.cpp): `src/queue.cpp`
- [Queue API](https://github.com/sushant-demn/sustify/blob/master/headers/queue.h): `headers/queue.h`

### Audio Playback

- [Audio Engine](https://github.com/sushant-demn/sustify/blob/master/src/audio.cpp): `src/audio.cpp`
- [Audio API](https://github.com/sushant-demn/sustify/blob/master/headers/audio.h): `headers/audio.h`
- [Miniaudio Runtime](https://github.com/sushant-demn/sustify/blob/master/include/miniaudio.h): `include/miniaudio.h`

### Other components

- **Listener**
- **Native WebView**
- **TagLib**

## Connections

- Listener → UI Document: uses (evidence: `README.md`)
- WebView Host → UI Document: loads (evidence: `src/window.cpp`)
- WebView Host → Native WebView: creates and runs (evidence: `src/window.cpp`)
- WebView Host → WebView Bindings: registers (evidence: `src/window.cpp`)
- WebView Host → Audio Engine: initializes (evidence: `src/window.cpp`)
- UI Controls → WebView Bindings: invokes bridge
- WebView Bindings → File Selection: selects file (evidence: `src/bindings.cpp`)
- File Selection → File Dialogs: opens dialog (evidence: `src/file_system.cpp`)
- WebView Bindings → Track Queue: dispatches controls (evidence: `src/bindings.cpp`)
- WebView Bindings → Audio Engine: controls playback (evidence: `src/bindings.cpp`)
- Track Queue → Audio Engine: starts and seeks (evidence: `src/queue.cpp`)
- Track Queue → TagLib: reads metadata (evidence: `README.md`)
- Audio Engine → Miniaudio Runtime: uses engine (evidence: `src/audio.cpp`)
- UI Document → UI Controls: loads
- UI Document → UI Styling: styles with
