# jmshrv/finamp architecture

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

- Interactive diagram: https://gitdiagram.com/jmshrv/finamp
- Repository: https://github.com/jmshrv/finamp

## Overview

##### Project type and purpose
- This is a cross-platform mobile application built with Flutter.
- Purpose: A Jellyfin music player (“Finamp”) for Android and iOS providing streaming, offline downloads, transcoding, dynamic theming, and background playback.

##### File structure
- Top-level:
- android/ and ios/ contain the native host projects and platform-specific entry points (MainActivity.kt, AppDelegate.swift).
- lib/ holds the Dart code subdivided into:
– components/ (reusable UI widgets)
– screens/ (page-level widgets implementing views)
– services/ (business logic, API helpers, state streams, download manager, audio service)
– models/ (data structures and generated code from JSON schemas)
– main.dart (app bootstrap)
– l10n/ (localization resources)
- config: pubspec.yaml (dependencies), .github/workflows (CI), fastlane (release metadata), flutter_launcher_icons, l10n.yaml.

##### Extract insights from README
- Fluent user experience targeting Jellyfin servers only.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "Flutter UI Layer"
        direction TB
        MusicScreen["MusicScreen"]:::ui
        PlayerScreen["PlayerScreen"]:::ui
        SettingsScreen["SettingsScreen"]:::ui
        SplashScreen["SplashScreen"]:::ui
        AlbumScreen["AlbumScreen"]:::ui
        ArtistScreen["ArtistScreen"]:::ui
        DownloadsScreen["DownloadsScreen"]:::ui
        DownloadsErrorScreen["DownloadsErrorScreen"]:::ui
        AudioServiceSettingsScreen["AudioServiceSettingsScreen"]:::ui
        LayoutSettingsScreen["LayoutSettingsScreen"]:::ui
        InteractionSettingsScreen["InteractionSettingsScreen"]:::ui
        LanguageSelectionScreen["LanguageSelectionScreen"]:::ui
        TabsSettingsScreen["TabsSettingsScreen"]:::ui
        TranscodingSettingsScreen["TranscodingSettingsScreen"]:::ui
        UserSelector["UserSelector"]:::ui
        ViewSelector["ViewSelector"]:::ui
    end

    %% Components
    subgraph "Reusable Components"
        direction TB
        AlbumImage["album_image.dart"]:::ui
        ConfirmationPromptDialog["confirmation_prompt_dialog.dart"]:::ui
        ErrorSnackbar["error_snackbar.dart"]:::ui
        NowPlayingBar["now_playing_bar.dart"]:::ui
        ViewIcon["view_icon.dart"]:::ui
    end

    %% Business Logic Layer
    subgraph "Domain/Business Logic Layer"
        direction TB
        JellyfinApiClient["jellyfin_api.chopper.dart"]:::logic
        JellyfinApiHelper["jellyfin_api_helper.dart"]:::logic
        DownloadsHelper["downloads_helper.dart"]:::logic
        OfflineListenHelper["offline_listen_helper.dart"]:::logic
        DownloadUpdateStream["download_update_stream.dart"]:::logic
        AudioServiceHelper["audio_service_helper.dart"]:::logic
        MediaStateStream["media_state_stream.dart"]:::logic
        ProgressStateStream["progress_state_stream.dart"]:::logic
        MusicPlayerBackgroundTask["music_player_background_task.dart"]:::logic
        SyncHelper["sync_helper.dart"]:::logic
        GenerateSubtitle["generate_subtitle.dart"]:::logic
        FinampSettingsHelper["finamp_settings_helper.dart"]:::logic
        ThemeModeHelper["theme_mode_helper.dart"]:::logic
        LocaleHelper["locale_helper.dart"]:::logic
        SetupLogging["setup_logging.dart"]:::logic
        ChopperAggregateLogger["chopper_aggregate_logger.dart"]:::logic
        HttpAggregateLoggingInterceptor["http_aggregate_logging_interceptor.dart"]:::logic
        FinampLogsHelper["finamp_logs_helper.dart"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Models["jellyfin_models.dart / finamp_models.dart"]:::data
        ThemeModeAdapter["theme_mode_adapter.dart"]:::data
        LocaleAdapter["locale_adapter.dart"]:::data
        Localization["l10n/app_*.arb & l10n.dart"]:::data
    end

    %% Platform Integration
    subgraph "Platform Integration"
        direction TB
        AndroidHost["MainActivity.kt"]:::platform
        iOSHost["AppDelegate.swift"]:::platform
        BackgroundTaskReg["music_player_background_task.dart"]:::platform
    end

    %% External Systems
    subgraph "External Systems & CI/CD"
        direction TB
        JellyfinServer["Jellyfin Server (REST API)"]:::external
        GitHubActions[".github/workflows/build.yml"]:::external
        Fastlane["fastlane/"]:::external
        Pubspec["pubspec.yaml"]:::external
    end

    %% Relationships
    MusicScreen -->|uses| JellyfinApiHelper
    PlayerScreen -->|controls| AudioServiceHelper
    SettingsScreen -->|reads/writes| FinampSettingsHelper
    DownloadsScreen -->|uses| DownloadsHelper
    JellyfinApiHelper -->|via| JellyfinApiClient
    DownloadsHelper -->|writes| ThemeModeAdapter
    AudioServiceHelper -->|spawns| MusicPlayerBackgroundTask
    MusicPlayerBackgroundTask -->|registers| AndroidHost
    MusicPlayerBackgroundTask -->|registers| iOSHost
    JellyfinApiClient -->|fetches| JellyfinServer
    DownloadUpdateStream -->|streams| DownloadsScreen
    MediaStateStream -->|streams| PlayerScreen
    ThemeModeHelper -->|updates| MusicScreen
    LocaleHelper -->|updates| LanguageSelectionScreen
    Models -->|used by| JellyfinApiHelper
    ThemeModeAdapter -->|persistent| SettingsScreen
    LocaleAdapter -->|persistent| SettingsScreen
    Localization -->|provides| MusicScreen
    GitHubActions -->|builds| Pubspec
    Fastlane -->|releases| Pubspec

    %% Click events
    click MusicScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/music_screen.dart"
    click PlayerScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/player_screen.dart"
    click SettingsScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/settings_screen.dart"
    click SplashScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/splash_screen.dart"
    click AlbumScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/album_screen.dart"
    click ArtistScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/artist_screen.dart"
    click DownloadsScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/downloads_screen.dart"
    click DownloadsErrorScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/downloads_error_screen.dart"
    click AudioServiceSettingsScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/audio_service_settings_screen.dart"
    click LayoutSettingsScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/layout_settings_screen.dart"
    click InteractionSettingsScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/interaction_settings_screen.dart"
    click LanguageSelectionScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/language_selection_screen.dart"
    click TabsSettingsScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/tabs_settings_screen.dart"
    click TranscodingSettingsScreen "https://github.com/jmshrv/finamp/blob/main/lib/screens/transcoding_settings_screen.dart"
    click UserSelector "https://github.com/jmshrv/finamp/blob/main/lib/screens/user_selector.dart"
    click ViewSelector "https://github.com/jmshrv/finamp/blob/main/lib/screens/view_selector.dart"
    click AlbumImage "https://github.com/jmshrv/finamp/blob/main/lib/components/album_image.dart"
    click ConfirmationPromptDialog "https://github.com/jmshrv/finamp/blob/main/lib/components/confirmation_prompt_dialog.dart"
    click ErrorSnackbar "https://github.com/jmshrv/finamp/blob/main/lib/components/error_snackbar.dart"
    click NowPlayingBar "https://github.com/jmshrv/finamp/blob/main/lib/components/now_playing_bar.dart"
    click ViewIcon "https://github.com/jmshrv/finamp/blob/main/lib/components/view_icon.dart"
    click JellyfinApiClient "https://github.com/jmshrv/finamp/blob/main/lib/services/jellyfin_api.chopper.dart"
    click JellyfinApiHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/jellyfin_api_helper.dart"
    click DownloadsHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/downloads_helper.dart"
    click OfflineListenHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/offline_listen_helper.dart"
    click DownloadUpdateStream "https://github.com/jmshrv/finamp/blob/main/lib/services/download_update_stream.dart"
    click AudioServiceHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/audio_service_helper.dart"
    click MediaStateStream "https://github.com/jmshrv/finamp/blob/main/lib/services/media_state_stream.dart"
    click ProgressStateStream "https://github.com/jmshrv/finamp/blob/main/lib/services/progress_state_stream.dart"
    click MusicPlayerBackgroundTask "https://github.com/jmshrv/finamp/blob/main/lib/services/music_player_background_task.dart"
    click SyncHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/sync_helper.dart"
    click GenerateSubtitle "https://github.com/jmshrv/finamp/blob/main/lib/services/generate_subtitle.dart"
    click FinampSettingsHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/finamp_settings_helper.dart"
    click ThemeModeHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/theme_mode_helper.dart"
    click LocaleHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/locale_helper.dart"
    click SetupLogging "https://github.com/jmshrv/finamp/blob/main/lib/setup_logging.dart"
    click ChopperAggregateLogger "https://github.com/jmshrv/finamp/blob/main/lib/services/chopper_aggregate_logger.dart"
    click HttpAggregateLoggingInterceptor "https://github.com/jmshrv/finamp/blob/main/lib/services/http_aggregate_logging_interceptor.dart"
    click FinampLogsHelper "https://github.com/jmshrv/finamp/blob/main/lib/services/finamp_logs_helper.dart"
    click Models "https://github.com/jmshrv/finamp/blob/main/lib/models/jellyfin_models.dart"
    click ThemeModeAdapter "https://github.com/jmshrv/finamp/blob/main/lib/models/theme_mode_adapter.dart"
    click LocaleAdapter "https://github.com/jmshrv/finamp/blob/main/lib/models/locale_adapter.dart"
    click Localization "https://github.com/jmshrv/finamp/blob/main/lib/l10n/app_en.arb"
    click AndroidHost "https://github.com/jmshrv/finamp/blob/main/android/app/src/main/kotlin/com/unicornsonlsd/finamp/MainActivity.kt"
    click iOSHost "https://github.com/jmshrv/finamp/blob/main/ios/Runner/AppDelegate.swift"
    click GitHubActions "https://github.com/jmshrv/finamp/blob/main/.github/workflows/build.yml"
    click Fastlane "https://github.com/jmshrv/finamp/tree/main/fastlane/"
    click Pubspec "https://github.com/jmshrv/finamp/blob/main/pubspec.yaml"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000
    classDef logic fill:#90EE90,stroke:#000
    classDef data fill:#FFA500,stroke:#000
    classDef platform fill:#D3D3D3,stroke:#000
    classDef external fill:#DDA0DD,stroke:#000
```
