How 143mailliw/hummingbird works
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)