# thekoon0456/lilsmusic architecture

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

- Interactive diagram: https://gitdiagram.com/thekoon0456/lilsmusic
- Repository: https://github.com/thekoon0456/lilsmusic

## Overview

##### Project type and purpose
- LilsMusic is an iOS client application (UIKit-based) for streaming and managing music and music videos.
- It follows a MVVM-Coordinator (MVVM-C) architecture, employs a Repository layer for data persistence (Realm) and remote calls (MusicKit, Apple Music API), uses RxSwift/SwiftConcurrency for async flows, and has a WidgetKit extension.

##### File structure and map to architectural layers
- App: AppDelegate, SceneDelegate → application entry point, scene lifecycle, initial coordinator.
- Presenter: split by “Scene” modules (Launch, Library, MusicList, MusicPlayer, MusicRecommend, Reels)
– Each Scene folder contains:
· Coordinator → handles navigation flows
· ViewController (in “View”) → UIKit screens
· ViewModel (in “ViewModel”) → business logic, exposes Input/Output streams
· Cell/View subfolders → reusable UI components
- Data:
– Model → domain entities (UserLibrary, UserSetting…)
– Repository → protocols + implementations (MusicAPIManager, UserPlaylistRepository)
- Manager: singletons handling cross-cutting concerns (FMMusicPlayer, SubscriptionManager, UserDefaultsManager)
- CommonUI/Base: shared UI controls and base classes for views, cells, view controllers
- Protocol: definition of Coordinator, Repository, ViewModel interfaces
- Resources: asset catalog, storyboards, Info.plist
- LilsMusicWidget: WidgetKit extension for home-screen widget

##### README for technology stack & key interactions
- MVVM-C with Input/Output binding (RxSwift + async/await)
- MusicKit, AVFoundation/AVKit for playback & streaming
- Realm for local caching and real-time updates to UI via notification tokens
- Firebase for analytics/crash reporting
- Kingfisher for image loading
- SnapKit for layout
- Compositional Layout for complex collection view layouts

1. Mobile Client (iOS App)
- UI Layer
– Views / ViewControllers
– Coordinators
- Presentation Layer
– ViewModels (RxSwift / SwiftConcurrency bindings)
- Business Logic Layer
– Managers (Player, Subscription, Settings)
– Repositories (protocols + implementations)
- Data Layer
– Local Database (Realm)
– Remote API (MusicKit / Apple Music API via MusicAPIManager)
2. Widget Extension (LilsMusicWidget)
- WidgetKit entry point → fetches data via Repository / Manager
3. External Services
- Apple Music service (catalog, playback entitlement)
- Firebase (Analytics, Crashlytics)
- Asset CDN (Kingfisher image URLs)

##### Relationships & data flows
- User taps UI → ViewController sends event to ViewModel Input
- ViewModel processes, calls Repository or Manager (via protocol)
- Repository delegates to:
– MusicAPIManager → MusicKit / Apple Music API → network → returns songs/playlists
– Realm Repository → local cache updates → emits notifications → ViewModel observes & publishes to Output
- ViewModel Output → bound to ViewController UI elements via RxSwift / Combine or async/await bridges
- Coordinator listens to ViewModel to trigger navigation (present player, subscription offer)
- Player Manager wraps AVQueuePlayer / AVPlayer → streams audio/video → updates current track → publishes via BehaviorSubject → ViewModel → UI
- WidgetKit uses the same Repository layer or direct Manager calls to fetch snapshot data

##### Architectural patterns & design principles
- MVVM-C: clear separation of UI, presentation, business logic, and navigation
- Repository Pattern: abstracts data sources, enforces protocol contracts
- Singleton Managers for cross-cutting concerns (player, subscription, user defaults)
- Input/Output binding ensures unidirectional data flow, testability
- Code-based UI + Compositional Layout for dynamic collection views
- Reactive Streams (RxSwift) + SwiftConcurrency for unified async behavior

##### Elements
- Clear labels for modules: e.g., “MusicListScene Coordinator”, “MusicListViewModel”, “MusicListViewController”
– Event flow (UI → VM_Input)
– Data flow (VM → Repo → API/DB → VM_Output → UI)
– Navigation flow (VM → Coordinator → UI)
– Playback flow (Player Manager → AVPlayer → streaming source)
- Notes on side for major frameworks: RxSwift, SwiftConcurrency, MusicKit, Realm, Firebase

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        LaunchVC["LaunchViewController"]:::ui
        LibraryVC["LibraryViewController"]:::ui
        MusicListVC["MusicListViewController"]:::ui
        MusicPlayerVC["MusicPlayerViewController"]:::ui
        MusicRecommendVC["MusicRecommendViewController"]:::ui
        ReelsVC["ReelsViewController"]:::ui
    end

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        LaunchVM["LaunchViewModel"]:::vm
        LibraryVM["LibraryViewModel"]:::vm
        MusicListVM["MusicListViewModel"]:::vm
        MusicPlayerVM["MusicPlayerViewModel"]:::vm
        MusicRecommendVM["MusicRecommendViewModel"]:::vm
        ReelsVM["ReelsViewModel"]:::vm
        ReelsCellVM["ReelsCellViewModel"]:::vm
    end

    %% Coordinators
    subgraph "Coordinators" 
        direction TB
        AppCoord["AppCoordinator"]:::coord
        LibraryCoord["LibraryCoordinator"]:::coord
        MusicListCoord["MusicListCoordinator"]:::coord
        MusicPlayerCoord["MusicPlayerCoordinator"]:::coord
        MusicRecommendCoord["MusicRecommendCoordinator"]:::coord
        ReelsCoord["ReelsCoordinator"]:::coord
    end

    %% Business Logic
    subgraph "Business Logic" 
        direction TB
        PlayerMgr["FMMusicPlayer"]:::mgr
        SubMgr["SubscriptionManager"]:::mgr
        UDManager["UserDefaultsManager"]:::mgr
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        UserLib["UserLibrary (Model)"]:::model
        UserSet["UserSetting (Model)"]:::model
        MusicAPI["MusicAPIManager"]:::repo
        UserPlaylist["UserPlaylistRepository"]:::repo
        RealmDB["Realm Database"]:::db
        RemoteAPI["MusicKit/Apple Music API"]:::external
    end

    %% Widget Extension
    subgraph "Widget Extension" 
        direction TB
        WidgetEntry["LilsMusicWidget"]:::widget
        WidgetBundle["LilsMusicWidgetBundle"]:::widget
    end

    %% Shared Modules
    subgraph "Shared & Common" 
        direction TB
        Protocols["Protocol Definitions"]:::util
        BaseUI["Base & CommonUI"]:::util
        Resources["Resources"]:::util
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Firebase["Firebase (Analytics/Crash)"]:::external
        CDN["Asset CDN (Kingfisher)"]:::external
    end

    %% App Entry
    subgraph "App Entry"
        direction TB
        AppDel["AppDelegate"]:::entry
        SceneDel["SceneDelegate"]:::entry
    end

    %% Connections: UI to VM
    LaunchVC -->|"input events"| LaunchVM
    LibraryVC -->|"input events"| LibraryVM
    MusicListVC -->|"input events"| MusicListVM
    MusicPlayerVC -->|"input events"| MusicPlayerVM
    MusicRecommendVC -->|"input events"| MusicRecommendVM
    ReelsVC -->|"input events"| ReelsVM

    %% VM to Coordinators
    LaunchVM -->|"navigation"| AppCoord
    LibraryVM -->|"navigation"| LibraryCoord
    MusicListVM -->|"navigation"| MusicListCoord
    MusicPlayerVM -->|"navigation"| MusicPlayerCoord
    MusicRecommendVM -->|"navigation"| MusicRecommendCoord
    ReelsVM -->|"navigation"| ReelsCoord

    %% VM to Data & Managers
    LaunchVM -->|"calls repo/manager"| MusicAPI
    LibraryVM -->|"calls repo/manager"| UserPlaylist
    MusicListVM -->|"calls repo/manager"| MusicAPI
    MusicPlayerVM -->|"controls"| PlayerMgr
    MusicRecommendVM -->|"calls repo"| MusicAPI
    ReelsVM -->|"calls repo"| MusicAPI

    %% Managers to External
    PlayerMgr -->|stream| RemoteAPI
    SubMgr -->|validate| RemoteAPI
    UDManager -->|persist| Resources

    %% Repositories to DB & RemoteAPI
    MusicAPI -->|network| RemoteAPI
    UserPlaylist -->|cache| RealmDB

    %% Realm notifications to VM
    RealmDB -->|"notifications"| LibraryVM
    RealmDB -->|"notifications"| UserLib
    RealmDB -->|"notifications"| UserSet

    %% Widget flow
    WidgetEntry -->|"uses repo/manager"| MusicAPI
    WidgetBundle -->|"uses repo/manager"| UserPlaylist

    %% Side dependencies
    Protocols -->|interfaces| AppCoord
    Protocols -->|interfaces| LibraryCoord
    Protocols -->|interfaces| MusicListCoord
    Protocols -->|interfaces| MusicPlayerCoord
    Protocols -->|interfaces| MusicRecommendCoord
    Protocols -->|interfaces| ReelsCoord
    Protocols -->|interfaces| LaunchVM
    Protocols -->|interfaces| LibraryVM
    BaseUI -->|inherits| LaunchVC
    BaseUI -->|inherits| LibraryVC
    BaseUI -->|inherits| MusicListVC
    Resources -->|assets/storyboards| LaunchVC
    Resources -->|assets/storyboards| SceneDel

    AppDel -->|"initializes"| AppCoord
    SceneDel -->|"manages scenes"| AppCoord

    Firebase -->|analytics| AppDel
    CDN -->|images| MusicListVC

    %% Click Events
    click AppDel "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/App/AppDelegate.swift"
    click SceneDel "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/App/SceneDelegate.swift"
    click LaunchVC "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/LaunchScene/LaunchViewController.swift"
    click LibraryVC "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/LibraryScene/View/LibraryViewController.swift"
    click MusicListVC "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicListScene/View/MusicListViewController.swift"
    click MusicPlayerVC "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicPlayerScene/View/MusicPlayerViewController.swift"
    click MusicRecommendVC "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicRecommendScene/View/MusicRecommendViewController.swift"
    click ReelsVC "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/ReelsScene/View/ReelsViewController.swift"
    click LibraryVM "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/LibraryScene/ViewModel/LibraryViewModel.swift"
    click MusicListVM "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicListScene/ViewModel/MusicListViewModel.swift"
    click MusicPlayerVM "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicPlayerScene/ViewModel/MusicPlayerViewModel.swift"
    click MusicRecommendVM "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicRecommendScene/ViewModel/MusicRecommendViewModel.swift"
    click ReelsVM "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/ReelsScene/ViewModel/ReelsViewModel.swift"
    click ReelsCellVM "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/ReelsScene/ViewModel/ReelsCellViewModel.swift"
    click AppCoord "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/AppCoordinator.swift"
    click LibraryCoord "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/LibraryScene/LibraryCoordinator.swift"
    click MusicListCoord "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicListScene/MusicListCoordinator.swift"
    click MusicPlayerCoord "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicPlayerScene/MusicPlayerCoordinator.swift"
    click MusicRecommendCoord "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/MusicRecommendScene/MusicRecommendCoordinator.swift"
    click ReelsCoord "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Presenter/ReelsScene/ReelsCoordinator.swift"
    click PlayerMgr "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Manager/FMMusicPlayer.swift"
    click SubMgr "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Manager/SubscriptionManager.swift"
    click UDManager "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Manager/UserDefaultsManager.swift"
    click UserLib "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Data/Model/UserLibrary.swift"
    click UserSet "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Data/Model/UserSetting.swift"
    click MusicAPI "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Data/Repository/MusicAPIManager.swift"
    click UserPlaylist "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusic/Data/Repository/UserPlaylistRepository.swift"
    click BaseUI "https://github.com/thekoon0456/lilsmusic/tree/main/LilsMusic/LilsMusic/Base"
    click Protocols "https://github.com/thekoon0456/lilsmusic/tree/main/LilsMusic/LilsMusic/Protocol"
    click Resources "https://github.com/thekoon0456/lilsmusic/tree/main/LilsMusic/LilsMusic/Resources"
    click WidgetEntry "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusicWidget/LilsMusicWidget.swift"
    click WidgetBundle "https://github.com/thekoon0456/lilsmusic/blob/main/LilsMusic/LilsMusicWidget/LilsMusicWidgetBundle.swift"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef vm fill:#D5F5E3,stroke:#1D8348,stroke-width:1px
    classDef coord fill:#FDEBD0,stroke:#CA6F1E,stroke-width:1px
    classDef mgr fill:#FCF3CF,stroke:#B7950B,stroke-width:1px
    classDef repo fill:#E8DAEF,stroke:#6C3483,stroke-width:1px
    classDef model fill:#D1F2EB,stroke:#117864,stroke-width:1px
    classDef db fill:#EBDEF0,stroke:#7D3C98,stroke-width:1px
    classDef external fill:#F2F3F4,stroke:#566573,stroke-width:1px,stroke-dasharray: 5 5
    classDef util fill:#F5EEF8,stroke:#7D3C98,stroke-width:1px,stroke-dasharray: 2 2
    classDef entry fill:#FADBD8,stroke:#922B21,stroke-width:1px
    classDef widget fill:#D6EAF8,stroke:#1B4F72,stroke-dasharray: 3 3
```
