# temka300/local-music-player architecture

> Architecture diagram of the GitHub repository temka300/local-music-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/temka300/local-music-player
- Repository: https://github.com/temka300/local-music-player

## Overview

##### Project Type & Purpose
- This is a **desktop full-stack application**: a local music player with GUI, business logic, database, and audio engine.
- Purpose: manage and play local audio files in a Spotify-like interface (metadata extraction, playlists, error-resilient playback).

##### File Structure
Top-level directories:
- core/      – business logic (audio playback, metadata, organization, downloading)
- gui/       – presentation layer (tkinter windows, dialogs, widgets)
- utils/     – shared constants, theming
- workers/   – background threads (file import scanning)
- main.py    – application entry point
- launch_music_player.bat & requirements.txt – deployment scripts
Other artifacts: SQLite database (auto-created at runtime), external Python libs (pygame, mutagen, pillow).

##### Extract Architectural Insights from the README
- **Layers**: UI (gui), Application Core (core), Data (SQLite), Background Workers (workers), Utilities (utils).
- **External Dependencies**:
– Audio: pygame (ModPlug), fallback strategies
– Metadata: mutagen
– Images: Pillow
– GUI: tkinter
– DB: sqlite3 (standard library)

##### Main Components
a. **Frontend (GUI Layer)**
– MainWindow (gui/main_window.py)
– Dialogs (CreatePlaylistDialog, YouTubeDownloadDialog)
– Widgets (EditableColumnsDelegate, ScrollingLabel)
b. **Backend (Core Layer)**
– AudioPlayer (core/audio_player.py)
– MetadataManager (core/metadata.py)
– DatabaseManager (core/database.py)
– Organizer (core/organizer.py)
– YouTubeDownloader (core/youtube_downloader.py)
– AlbumArtHandler (core/album_art.py)
c. **Workers Layer**
– FileImportThread (workers/file_import_thread.py) – recursive folder/file scanning
d. **Utilities**
– Constants & Themes (utils/constants.py, utils/themes.py)
e. **Data Store**
– local SQLite database (Songs, Playlists, PlaylistSongs tables)
f. **External Libraries**
– pygame, mutagen, Pillow, tkinter, sqlite3

##### Relationships & Data Flows
- **User Actions** (GUI) → invoke **Core Services** via controller callbacks in main.py
- **Core Services** call **DatabaseManager** for CRUD on metadata and playlists
- **AudioPlayer** loads files, uses pygame fallback strategies, reports status back to GUI
- **Workers/FileImportThread** runs in background: reads file paths, extracts metadata (via MetadataManager), writes to DB
- **YouTubeDownloader** optionally fetches audio, hands off to Organizer & DatabaseManager
- **Utilities** supply theme settings and constants to both GUI and Core

##### Architectural Patterns & Principles
- **Layered Architecture**: GUI ↔ Core ↔ Data
- **Event-Driven UI**: user events ⇒ callbacks ⇒ service layer
- **Worker Threads** for long-running tasks (file scanning) to keep UI responsive
- **Repository Pattern** in DatabaseManager for decoupled data access
- **Strategy Pattern** in AudioPlayer for fallback audio init

- **Thread Indicators** (UI main thread vs. worker threads)
- **External Dependencies** clearly outside your main boundary

## Diagram (Mermaid)

```mermaid
graph TB
    %% External User
    User((User)):::external

    %% Launch & Entry
    Launch[/"launch_music_player.bat"/]:::launch
    EntryPoint[/"main.py"/]:::entry

    %% GUI Layer
    subgraph "GUI Layer"
        direction TB
        MainWindow["MainWindow"]:::gui
        CreatePlaylistDialog["CreatePlaylistDialog"]:::gui
        YouTubeDownloadDialog["YouTubeDownloadDialog"]:::gui
        EditableColumnsDelegate["EditableColumnsDelegate"]:::gui
        ScrollingLabel["ScrollingLabel"]:::gui
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        AudioPlayer["AudioPlayer"]:::core
        MetadataManager["MetadataManager"]:::core
        DatabaseManager["DatabaseManager"]:::core
        Organizer["Organizer"]:::core
        YouTubeDownloader["YouTubeDownloader"]:::core
        AlbumArtHandler["AlbumArtHandler"]:::core
    end

    %% Workers Layer
    subgraph "Workers"
        direction TB
        FileImportThread["FileImportThread"]:::workers
    end

    %% Utils Layer
    subgraph "Utils"
        direction TB
        Constants["Constants"]:::utils
        Themes["Themes"]:::utils
    end

    %% Data Store
    Database[(SQLite DB)]:::db

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        Pygame("pygame"):::ext
        Mutagen("mutagen"):::ext
        Pillow("Pillow"):::ext
        Tkinter("tkinter"):::ext
        SQLite3("sqlite3"):::ext
    end

    %% Connections
    User -->|"launch app"| Launch
    Launch -->|runs| EntryPoint

    EntryPoint -->|init UI| MainWindow
    EntryPoint -->|start worker| FileImportThread

    User -->|interacts| MainWindow
    MainWindow -->|open| CreatePlaylistDialog
    MainWindow -->|open| YouTubeDownloadDialog
    MainWindow -->|use| EditableColumnsDelegate
    MainWindow -->|use| ScrollingLabel

    MainWindow -->|"playback request"| AudioPlayer
    MainWindow -->|"metadata query"| MetadataManager
    MainWindow -->|"DB CRUD"| DatabaseManager
    MainWindow -->|"download request"| YouTubeDownloader

    AudioPlayer -->|load audio| Pygame
    AudioPlayer -->|fallback init| Pygame
    AudioPlayer -->|image ops| Pillow

    MetadataManager -->|extract tags| Mutagen
    AlbumArtHandler -->|handle images| Pillow

    YouTubeDownloader -->|fetch stream| Pygame
    YouTubeDownloader -->|delegate| Organizer

    FileImportThread -->|scan files| Constants
    FileImportThread -->|extract metadata| MetadataManager
    FileImportThread -->|write to DB| DatabaseManager

    Organizer -->|organize files| DatabaseManager
    DatabaseManager -->|persist/retrieve| Database

    Constants -->|provide| MainWindow
    Themes -->|provide| MainWindow

    Database -->|via| SQLite3

    %% Click Events
    click MainWindow "https://github.com/temka300/local-music-player/blob/main/gui/main_window.py"
    click CreatePlaylistDialog "https://github.com/temka300/local-music-player/blob/main/gui/dialogs/create_playlist_dialog.py"
    click YouTubeDownloadDialog "https://github.com/temka300/local-music-player/blob/main/gui/dialogs/youtube_download_dialog.py"
    click EditableColumnsDelegate "https://github.com/temka300/local-music-player/blob/main/gui/widgets/editable_columns_delegate.py"
    click ScrollingLabel "https://github.com/temka300/local-music-player/blob/main/gui/widgets/scrolling_label.py"
    click AudioPlayer "https://github.com/temka300/local-music-player/blob/main/core/audio_player.py"
    click MetadataManager "https://github.com/temka300/local-music-player/blob/main/core/metadata.py"
    click DatabaseManager "https://github.com/temka300/local-music-player/blob/main/core/database.py"
    click Organizer "https://github.com/temka300/local-music-player/blob/main/core/organizer.py"
    click YouTubeDownloader "https://github.com/temka300/local-music-player/blob/main/core/youtube_downloader.py"
    click AlbumArtHandler "https://github.com/temka300/local-music-player/blob/main/core/album_art.py"
    click FileImportThread "https://github.com/temka300/local-music-player/blob/main/workers/file_import_thread.py"
    click Constants "https://github.com/temka300/local-music-player/blob/main/utils/constants.py"
    click Themes "https://github.com/temka300/local-music-player/blob/main/utils/themes.py"
    click EntryPoint "https://github.com/temka300/local-music-player/blob/main/main.py"
    click Launch "https://github.com/temka300/local-music-player/blob/main/launch_music_player.bat"
    click SQLite3 "https://github.com/temka300/local-music-player/blob/main/requirements.txt"

    %% Styles
    classDef gui fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef workers fill:#FFA500,stroke:#000;
    classDef utils fill:#D3D3D3,stroke:#000;
    classDef db fill:#D2691E,stroke:#000,shape:cylinder;
    classDef ext fill:#FFF,stroke:#000,stroke-dasharray: 5 5;
    classDef external fill:#FFFFFF,stroke:#000,shape:circle;
    classDef launch fill:#FFFFFF,stroke:#000,stroke-dasharray:2 2;
    classDef entry fill:#FFFFFF,stroke:#000,stroke-dasharray:2 2;
```
