# 143mailliw/hummingbird architecture

> Architecture diagram of the GitHub repository 143mailliw/hummingbird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/143mailliw/hummingbird
- Repository: https://github.com/143mailliw/hummingbird

## Overview

##### Project Type and Purpose
- Hummingbird is a fully native cross-platform desktop music player written in Rust, with a GUI frontend (GPUI), a SQLite-backed library, audio playback engine, theming, and external scrobbling support.
- It is *not* a client-server or web app, but a layered desktop application with extension points (e.g., WASM plugins planned).

##### Break Out the Main Architectural Layers (Container Level)
a. Presentation Layer (UI)
b. Domain/Service Layer (Core Logic)
c. Infrastructure Layer (Persistence, Devices, External APIs)

- UI (Presentation)
– GPUI-based windowing & styling
– Components: library view, album/track listings, search, queue, settings dialog, theming subsystem
- Core Logic (Domain & Services)
– Library manager (scan filesystem, run SQL migrations, query via `queries/`)
– Playback engine (media decoding, queue, thread management)
– Settings manager (load/save via config files or environment)
– Services module (Last.fm scrobbling client)
- Infrastructure
– SQLite database (with migrations in `migrations/`)
– File system scanning (access to `assets/`, user music files)
– Audio device backends (CPAL, platform-specific implementations)
– External HTTP API (Last.fm)

##### Component-Level Detail Inside Each Container
- UI container:
– `ui/app.rs`, `ui/components/*`, `ui/library/*`, `ui/search/*`, `ui/theme.rs`
- Library manager:
– `src/library/scan.rs` (filesystem scanner)
– `src/library/db.rs` (DB connection & query execution)
– SQL files in `queries/library` and `queries/scan`
- Playback engine:
– `src/media` (decoders, metadata, traits)
– `src/playback` (queue, events, thread model)
- Services:
– `src/services/mmb/lastfm/*` (client, requests, types)
- Settings:
– `src/settings/*.rs` (storage paths, scan settings)

##### Architectural Patterns & Principles
- Layered architecture (Presentation → Domain → Infrastructure)
- Modularization by feature (`devices`, `media`, `library`, `playback`, `services`, `ui`)
- Clear separation between sync DB access and async media/playback threads
- Use of SQL migrations & query files for database schema/versioning
- Extension points planned via WASM (plugins for codecs, services, metadata)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    User["End-user"]:::external
    FileSystem["File System"]:::external
    LastFMAPI["Last.fm API"]:::external
    SystemAudio["System Audio"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer (UI)" 
        direction TB
        UIApp["ui/app.rs"]:::frontend
        UIComponents["ui/components/*"]:::frontend
        UILibraryUI["ui/library/*"]:::frontend
        UISearch["ui/search/*"]:::frontend
        UITheme["ui/theme.rs"]:::frontend
        UIAssets["ui/assets.rs"]:::frontend
        UIConstants["ui/constants.rs"]:::frontend
        UIMain["ui.rs"]:::frontend
    end

    %% Core Logic Layer
    subgraph "Core Logic (Domain & Services)"
        direction TB
        LibraryScan["library/scan.rs"]:::core
        LibraryDB["library/db.rs"]:::core
        LibraryTypes["library/types.rs"]:::core
        PlaybackMedia["media.rs & media/*"]:::core
        PlaybackCore["playback.rs & playback/*"]:::core
        ServicesCore["services.rs & services/*"]:::core
        SettingsCore["settings.rs & settings/*"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        SQLiteDB["SQLite Database"]:::infra
        Migrations["migrations/*"]:::infra
        BuildScript["build.rs"]:::infra
        Devices["devices.rs & devices/*"]:::infra
        AssetsFonts["assets/fonts/*"]:::infra
    end

    %% Interactions and Data Flows
    User -->|interacts with| UIApp
    UIApp -->|renders UI| UIComponents
    UIApp -->|calls| LibraryScan
    LibraryScan -->|scans| FileSystem
    LibraryScan -->|updates| LibraryDB
    LibraryDB -->|SQL query| SQLiteDB
    SQLiteDB -->|results| LibraryDB
    LibraryDB -->|returns data| UIApp
    UIApp -->|Play event| PlaybackCore
    PlaybackCore -->|uses decoder| PlaybackMedia
    PlaybackMedia -->|outputs audio| Devices
    Devices -->|to| SystemAudio
    PlaybackCore -->|thread events| UIApp
    UIApp -->|theme change| UITheme
    UITheme -->|loads| AssetsFonts
    UIApp -->|scrobble request| ServicesCore
    ServicesCore -->|HTTP POST scrobble| LastFMAPI
    LastFMAPI -->|response| ServicesCore
    ServicesCore -->|notification| UIApp

    %% Click Events
    click UIApp "https://github.com/143mailliw/hummingbird/blob/master/src/ui/app.rs"
    click UIComponents "https://github.com/143mailliw/hummingbird/tree/master/src/ui/components"
    click UILibraryUI "https://github.com/143mailliw/hummingbird/tree/master/src/ui/library"
    click UISearch "https://github.com/143mailliw/hummingbird/tree/master/src/ui/search"
    click UITheme "https://github.com/143mailliw/hummingbird/blob/master/src/ui/theme.rs"
    click UIAssets "https://github.com/143mailliw/hummingbird/blob/master/src/ui/assets.rs"
    click UIConstants "https://github.com/143mailliw/hummingbird/blob/master/src/ui/constants.rs"
    click UIMain "https://github.com/143mailliw/hummingbird/blob/master/src/ui.rs"
    click LibraryScan "https://github.com/143mailliw/hummingbird/blob/master/src/library/scan.rs"
    click LibraryDB "https://github.com/143mailliw/hummingbird/blob/master/src/library/db.rs"
    click LibraryTypes "https://github.com/143mailliw/hummingbird/blob/master/src/library/types.rs"
    click PlaybackMedia "https://github.com/143mailliw/hummingbird/blob/master/src/media.rs"
    click PlaybackMedia "https://github.com/143mailliw/hummingbird/tree/master/src/media"
    click PlaybackCore "https://github.com/143mailliw/hummingbird/blob/master/src/playback.rs"
    click PlaybackCore "https://github.com/143mailliw/hummingbird/blob/master/src/playback/events.rs"
    click PlaybackCore "https://github.com/143mailliw/hummingbird/blob/master/src/playback/interface.rs"
    click PlaybackCore "https://github.com/143mailliw/hummingbird/blob/master/src/playback/queue.rs"
    click PlaybackCore "https://github.com/143mailliw/hummingbird/blob/master/src/playback/thread.rs"
    click ServicesCore "https://github.com/143mailliw/hummingbird/blob/master/src/services.rs"
    click ServicesCore "https://github.com/143mailliw/hummingbird/blob/master/src/services/mmb.rs"
    click ServicesCore "https://github.com/143mailliw/hummingbird/blob/master/src/services/mmb/lastfm/client.rs"
    click ServicesCore "https://github.com/143mailliw/hummingbird/blob/master/src/services/mmb/lastfm/requests.rs"
    click ServicesCore "https://github.com/143mailliw/hummingbird/blob/master/src/services/mmb/lastfm/types.rs"
    click ServicesCore "https://github.com/143mailliw/hummingbird/blob/master/src/services/mmb/lastfm/util.rs"
    click SettingsCore "https://github.com/143mailliw/hummingbird/blob/master/src/settings.rs"
    click SettingsCore "https://github.com/143mailliw/hummingbird/blob/master/src/settings/scan.rs"
    click SettingsCore "https://github.com/143mailliw/hummingbird/blob/master/src/settings/storage.rs"
    click SQLiteDB "https://github.com/143mailliw/hummingbird/tree/master/migrations"
    click BuildScript "https://github.com/143mailliw/hummingbird/blob/master/build.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/errors.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/format.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/traits.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/resample.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/util.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/builtin/cpal.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/builtin/win_audiograph.rs"
    click Devices "https://github.com/143mailliw/hummingbird/blob/master/src/devices/builtin/dummy.rs"
    click Migrations "https://github.com/143mailliw/hummingbird/tree/master/migrations"
    click AssetsFonts "https://github.com/143mailliw/hummingbird/tree/master/assets/fonts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#4da3ff,stroke-width:1px
    classDef core fill:#d4edda,stroke:#3c763d,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:1px,stroke-dasharray: 5 5
```
