# ade-nugraha306/sky-project architecture

> Architecture diagram of the GitHub repository ade-nugraha306/sky-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ade-nugraha306/sky-project
- Repository: https://github.com/ade-nugraha306/sky-project

## Overview

Sky is a keyboard-first terminal music player. The main workflow starts in the TUI: it loads configuration and the SQLite library, lets users browse or filter tracks, then manages playback through a queue and audio player. Separate UI modes support folder selection and playlist management; scanning and metadata parsing populate the library. The excerpts show application startup, playback handling, persistence APIs, and selected UI behavior. Some scanner-to-metadata and decoder internals were not shown, so those links are omitted or marked unverified.

Main entry points: [`internal/tui/update.go`](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/update.go) (Player TUI), [`internal/tui/model.go`](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/model.go) (UI State), [`main.go`](https://github.com/ade-nugraha306/sky-project/blob/main/main.go) (Startup), [`internal/player/player.go`](https://github.com/ade-nugraha306/sky-project/blob/main/internal/player/player.go) (Audio Player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_entry["Startup<br/>[main.go]"]
  node_tui["Player TUI<br/>[update.go]"]
  node_ui_model["UI State<br/>[model.go]"]
  node_track_rows["Track Rows<br/>[item.go]"]
  node_folder_browser["Folder Browser<br/>[browser.go]"]
  node_folder_preview["Folder Preview<br/>[preview.go]"]
  node_views["Screen Views<br/>[view.go]"]
end

subgraph group_library["Music Library"]
  node_scanner["Folder Scanner<br/>[scanner.go]"]
  node_metadata["Metadata Parser<br/>[metadata.go]"]
end

subgraph group_playback["Playback"]
  node_queue["Playback Queue<br/>[queue.go]"]
  node_audio_player["Audio Player<br/>[player.go]"]
  node_decoder["Audio Decoder<br/>[decoder.go]"]
end

subgraph group_persistence["Persistence"]
  node_settings["Settings<br/>[config.go]"]
  node_library_db[("Track Catalog<br/>[tracks.go]")]
  node_playlist_db[("Playlist Store<br/>[playlists.go]")]
  node_db_open[("Database Setup<br/>[db.go]")]
end

node_user(("Listener"))
node_audio_output(("Audio Output"))

node_user -->|"operates"| node_tui
node_entry -->|"loads"| node_settings
node_entry -->|"opens"| node_db_open
node_entry -->|"constructs"| node_ui_model
node_entry -->|"runs"| node_tui
node_ui_model -->|"uses"| node_settings
node_ui_model -->|"uses"| node_db_open
node_ui_model -->|"creates"| node_audio_player
node_tui -->|"updates"| node_ui_model
node_tui -->|"loads tracks"| node_library_db
node_tui -->|"manages playlists"| node_playlist_db
node_tui -->|"shuffles and locates"| node_queue
node_tui -->|"starts playback"| node_audio_player
node_tui -->|"saves resume"| node_settings
node_tui -->|"updates"| node_folder_browser
node_tui -->|"requests preview"| node_folder_preview
node_tui -->|"uses items"| node_track_rows
node_views -.->|"renders items"| node_track_rows
node_scanner -.->|"supplies tracks"| node_library_db
node_metadata -.->|"enriches tracks"| node_scanner
node_tui -.->|"initiates scans"| node_scanner
node_library_db -->|"stores metadata fields"| node_metadata
node_playlist_db -->|"looks up tracks"| node_library_db
node_audio_player -.->|"decodes files"| node_decoder
node_audio_player -->|"plays audio"| node_audio_output

click node_entry "https://github.com/ade-nugraha306/sky-project/blob/main/main.go"
click node_settings "https://github.com/ade-nugraha306/sky-project/blob/main/internal/config/config.go"
click node_tui "https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/update.go"
click node_ui_model "https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/model.go"
click node_track_rows "https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/item.go"
click node_folder_browser "https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/browser.go"
click node_folder_preview "https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/preview.go"
click node_views "https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/view.go"
click node_scanner "https://github.com/ade-nugraha306/sky-project/blob/main/internal/library/scanner.go"
click node_metadata "https://github.com/ade-nugraha306/sky-project/blob/main/internal/library/metadata.go"
click node_library_db "https://github.com/ade-nugraha306/sky-project/blob/main/internal/db/tracks.go"
click node_playlist_db "https://github.com/ade-nugraha306/sky-project/blob/main/internal/db/playlists.go"
click node_db_open "https://github.com/ade-nugraha306/sky-project/blob/main/internal/db/db.go"
click node_queue "https://github.com/ade-nugraha306/sky-project/blob/main/internal/queue/queue.go"
click node_audio_player "https://github.com/ade-nugraha306/sky-project/blob/main/internal/player/player.go"
click node_decoder "https://github.com/ade-nugraha306/sky-project/blob/main/internal/player/decoder.go"

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_entry,node_tui,node_ui_model,node_track_rows,node_folder_browser,node_folder_preview,node_views toneBlue
class node_scanner,node_metadata toneAmber
class node_queue,node_audio_player,node_decoder toneMint
class node_settings,node_library_db,node_playlist_db,node_db_open toneRose
class node_user,node_audio_output toneIndigo
```

## Components

### Application UI

- [Startup](https://github.com/ade-nugraha306/sky-project/blob/main/main.go): `main.go`
- [Player TUI](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/update.go): `internal/tui/update.go`
- [UI State](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/model.go): `internal/tui/model.go`
- [Track Rows](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/item.go): `internal/tui/item.go`
- [Folder Browser](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/browser.go): `internal/tui/browser.go`
- [Folder Preview](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/preview.go): `internal/tui/preview.go`
- [Screen Views](https://github.com/ade-nugraha306/sky-project/blob/main/internal/tui/view.go): `internal/tui/view.go`

### Music Library

- [Folder Scanner](https://github.com/ade-nugraha306/sky-project/blob/main/internal/library/scanner.go): `internal/library/scanner.go`
- [Metadata Parser](https://github.com/ade-nugraha306/sky-project/blob/main/internal/library/metadata.go): `internal/library/metadata.go`

### Playback

- [Playback Queue](https://github.com/ade-nugraha306/sky-project/blob/main/internal/queue/queue.go): `internal/queue/queue.go`
- [Audio Player](https://github.com/ade-nugraha306/sky-project/blob/main/internal/player/player.go): `internal/player/player.go`
- [Audio Decoder](https://github.com/ade-nugraha306/sky-project/blob/main/internal/player/decoder.go): `internal/player/decoder.go`

### Persistence

- [Settings](https://github.com/ade-nugraha306/sky-project/blob/main/internal/config/config.go): `internal/config/config.go`
- [Track Catalog](https://github.com/ade-nugraha306/sky-project/blob/main/internal/db/tracks.go): `internal/db/tracks.go`
- [Playlist Store](https://github.com/ade-nugraha306/sky-project/blob/main/internal/db/playlists.go): `internal/db/playlists.go`
- [Database Setup](https://github.com/ade-nugraha306/sky-project/blob/main/internal/db/db.go): `internal/db/db.go`

### Other components

- **Listener**
- **Audio Output**

## Connections

- Listener → Player TUI: operates (evidence: `README.md`)
- Startup → Settings: loads (evidence: `main.go`)
- Startup → Database Setup: opens (evidence: `main.go`)
- Startup → UI State: constructs (evidence: `main.go`)
- Startup → Player TUI: runs (evidence: `main.go`)
- UI State → Settings: uses (evidence: `internal/tui/model.go`)
- UI State → Database Setup: uses (evidence: `internal/tui/model.go`)
- UI State → Audio Player: creates (evidence: `internal/tui/model.go`)
- Player TUI → UI State: updates (evidence: `internal/tui/update.go`)
- Player TUI → Track Catalog: loads tracks (evidence: `internal/tui/update.go`)
- Player TUI → Playlist Store: manages playlists (evidence: `internal/tui/update.go`)
- Player TUI → Playback Queue: shuffles and locates (evidence: `internal/tui/update.go`)
- Player TUI → Audio Player: starts playback (evidence: `internal/tui/update.go`)
- Player TUI → Settings: saves resume (evidence: `internal/tui/update.go`)
- Player TUI → Folder Browser: updates (evidence: `internal/tui/update.go`)
- Player TUI → Folder Preview: requests preview (evidence: `internal/tui/update.go`)
- Player TUI → Track Rows: uses items (evidence: `internal/tui/update.go`)
- Screen Views → Track Rows: renders items
- Folder Scanner → Track Catalog: supplies tracks
- Metadata Parser → Folder Scanner: enriches tracks
- Player TUI → Folder Scanner: initiates scans
- Track Catalog → Metadata Parser: stores metadata fields (evidence: `internal/db/tracks.go`)
- Playlist Store → Track Catalog: looks up tracks (evidence: `internal/db/playlists.go`)
- Audio Player → Audio Decoder: decodes files
- Audio Player → Audio Output: plays audio (evidence: `README.md`)