# nguyenkien/shortwave architecture

> Architecture diagram of the GitHub repository nguyenkien/shortwave, 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/nguyenkien/shortwave
- Repository: https://github.com/nguyenkien/shortwave

## Overview

##### Project type and purpose
- Shortwave is a desktop full-stack application written in Rust, targeting the GNOME desktop (and Linux phones via libadwaita). Its purpose is to provide an Internet radio player that fetches station data from a remote community database and lets users browse, play, and record streams.

##### File structure
- Top-level build & config files:
- Cargo.toml, Cargo.lock – Rust package and dependency manifest
- meson.build + meson_options.txt + build-aux/ – Meson build scripts, Flatpak manifest
- po/ – localization resources
- Source code (src/):
- src/ui/ – GTK UI layer (dialogs, pages, widgets)
- src/api/ – client, data models, station lookup and sorting logic
- src/audio/ – GStreamer audio backend, MPRIS integration, playback & recording state
- src/database/ – local SQLite connection, schema, migrations, queries, models
- src/device/ – device discovery (UPnP/Chromecast), casting logic, device models
- src/settings/ – settings manager abstraction over key/value storage
- src/app.rs, src/main.rs – application bootstrap and orchestration
- utils.rs, i18n.rs, path.rs – helper utilities

##### README insights
- Uses Flatpak + GNOME Builder for packaging
- Relies on radio-browser.info community database
- Adaptive UI via libadwaita/GTK
- Database migrations in data/database for local library storage
- Debug via Rust logging and backtraces

##### Main components and interactions
a. Components:
- UI Layer (GTK/libadwaita)
- Application Core (app.rs/orchestrator)
- API Client (http calls to radio-browser.info)
- Local Database (SQLite with migrations)
- Audio Backend (GStreamer, MPRIS, Recorder)
- Device Manager (UPnP/Chromecast, mDNS/SSDP)
- Settings Manager
- External Services: Internet (radio API), OS (DB file, audio subsystem, D-Bus for MPRIS)
b. Relationships:
1. UI → Core: user events (play, search, add station)
2. Core ↔ API Client: fetch station lists, covers, metadata
4. Core → Audio Backend: play/stop streams, record
5. Core → Device Manager: discover and cast to devices
6. UI ↔ Settings: read/write user preferences
7. Audio Backend ↔ D-Bus (MPRIS) ↔ Other apps
c. Architectural patterns:
- Layered architecture: UI → domain/core → data (API/DB) → external
- MVC/MVVM‐like separation in UI pages and models (e.g., station_model, track_model)
- Event‐driven playback & device discovery
d. Key technologies:
- Rust crates: reqwest/serde (API), rusqlite or diesel (DB), gstreamer-rs (audio), zbus (MPRIS), glib-rs/gtk4 (UI)
- Meson/Ninja build
- Flatpak sandboxing
- gettext/po for i18n

##### Detail without over-splitting
- Audio backend as one block even though it has submodules (player, recorder, MPRIS)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["UI Layer"]:::ui
    end

    %% Core Layer
    subgraph "Core Layer"
        Core["Application Core"]:::core
        Settings["Settings Manager"]:::core
        Utils["Utilities & Helpers"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        API["API Client"]:::data
        DB["Local Database"]:::data
    end

    %% Subsystems
    subgraph "Subsystems"
        Audio["Audio Backend"]:::subsys
        Device["Device Manager"]:::subsys
    end

    %% External Services
    subgraph "External Services"
        Cloud["radio-browser.info API"]:::external
        DBFile["OS DB File"]:::external
        AudioServer["Audio Server\n(PulseAudio/ALSA)"]:::external
        Dbus["D-Bus (MPRIS)"]:::external
    end

    %% Connections
    UI -->|"user events (play, search, add station)"| Core
    UI -->|"read/write prefs"| Settings
    Core -->|"fetch stations"| API
    Core -->|"persist favorite"| DB
    Core -->|"play stream / record"| Audio
    Core -->|"discover devices"| Device
    Core -->|"use utilities"| Utils
    API -->|"HTTP requests"| Cloud
    DB -->|"file storage"| DBFile
    Audio -->|"output audio"| AudioServer
    Audio -->|"MPRIS controls"| Dbus

    %% Click Events
    click UI "https://github.com/nguyenkien/shortwave/tree/main/src/ui/"
    click Core "https://github.com/nguyenkien/shortwave/blob/main/src/app.rs"
    click Core "https://github.com/nguyenkien/shortwave/blob/main/src/main.rs"
    click API "https://github.com/nguyenkien/shortwave/tree/main/src/api/"
    click DB "https://github.com/nguyenkien/shortwave/tree/main/src/database/"
    click DB "https://github.com/nguyenkien/shortwave/tree/main/data/database/migrations/"
    click Audio "https://github.com/nguyenkien/shortwave/tree/main/src/audio/"
    click Device "https://github.com/nguyenkien/shortwave/tree/main/src/device/"
    click Settings "https://github.com/nguyenkien/shortwave/tree/main/src/settings/"
    click Utils "https://github.com/nguyenkien/shortwave/blob/main/src/utils.rs"
    click Utils "https://github.com/nguyenkien/shortwave/blob/main/src/i18n.rs"
    click Utils "https://github.com/nguyenkien/shortwave/blob/main/src/path.rs"

    %% Styles
    classDef ui fill:#EEF5FF,stroke:#3B70FF,stroke-width:2px;
    classDef core fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
    classDef data fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px;
    classDef subsys fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px;
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:2px;
```
