# jamesbuhanan/songify architecture

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

- Interactive diagram: https://gitdiagram.com/jamesbuhanan/songify
- Repository: https://github.com/jamesbuhanan/songify

## Overview

##### Project type & purpose
- This is a multi‑module Android sample app showcasing “massively scalable” modular architecture.
- It uses a single‑Activity + Circuit navigation engine + Hilt DI + Gradle “focus” plugins to load only the modules you care about.
- Features are broken into `:feature:<name>:public`, `:feature:<name>:internal`, and `:feature:<name>:app` modules.
- Shared libraries (e.g. `:library:spotify`, `:library:retrofit`, `:library:design`, etc.) follow a public/​internal split for UseCases & implementations.

##### Main components
A. Build Infrastructure
– Gradle “build-logic” conventions & plugins (SongifyRootPlugin, SettingsPlugin, etc.)
– Gradle wrapper, `settings.gradle`, `mkdocs.yml`, detekt/lint configs, the “focus” plugin
B. Application Host
– `:app` module (EntryPointActivity, LemmusApplication)
– Hilt DI graph / AndroidInjector
– Circuit navigation engine
C. Feature Modules (per feature)
– Public (Screen key, data classes)
– Internal (Contract, Presenter, View, Compose UI)
– App (Hilt module wiring start screens)
D. Library Modules
– Common libraries: Compose‑Extensions, Coroutines, Design, Loading UI, BottomNavigation
– Domain/use‑case libraries: Home, Detail, Search, Premium, Session
– Network: Retrofit, Spotify API
E. External Services
– Spotify REST API
– CI/CD (affectedModuleDetector, GraphAssert)

##### Relationships & interactions
- The single `:app` module bootstraps Hilt and Circuit.
- Circuit routes ScreenKey → looks up the matching Presenter/View contributed by a `feature/*/internal` module.
- Presenters invoke UseCase interfaces from `library/*:public`.
- UseCase implementations live in `library/*:internal`, some of which call the `library/retrofit` module.
- `library/retrofit` module uses Retrofit + Moshi to call Spotify endpoints and returns model objects to UseCases.
- UI components (Jetpack Compose screens) render state from Presenters.
- Gradle “focus” plugin instructs the build system to only configure & compile the modules involved in the current workflow.

##### Architectural patterns & principles
– Clean Architecture (UI → Presentation → Domain → Data → External)
– Unidirectional Data Flow via Circuit (Presenter emits state → View renders → events back to Presenter)
– SOLID modularization: public vs internal boundaries enforced by GraphAssert
– Dependency Injection by Hilt modules in `feature/*:app` and `library/*:internal`

##### Final checklist
[ ] All layers clearly separated and labeled
[ ] Each module cluster labeled with its Gradle path
[ ] Callouts for key frameworks: Hilt, Circuit, Retrofit, Moshi, Gradle Focus

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure Layer
    subgraph "Infrastructure" 
        direction TB
        SongifyRootPlugin["SongifyRootPlugin"]:::infras
        SongifySettingsPlugin["SongifySettingsPlugin"]:::infras
        FocusPlugin["Focus Plugin"]:::infras
        SettingsGradle["settings.gradle"]:::infras
        Mkdocs["mkdocs.yml"]:::infras
        DetektConfig["detekt.yml"]:::infras
        AffectedModules["AffectedModules"]:::infras
        GraphAssert["GraphAssert"]:::infras
    end

    %% External Layer
    subgraph "External Services"
        SpotifyAPI["Spotify REST API"]:::external
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RetrofitModule["RetrofitModule"]:::internalLib
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        GetTracks["GetTracks"]:::publicLib
        GetHomeFeed["GetHomeFeed"]:::publicLib
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        DetailPresenter["DetailPresenter"]:::feature
        HomePresenter["HomePresenter"]:::feature
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        AlbumDetailScreen["AlbumDetailScreen"]:::feature
        CarouselLazyRow["CarouselLazyRow"]:::feature
    end

    %% Application Host
    subgraph "App Host"
        direction TB
        EntryPointActivity["EntryPointActivity"]:::appHost
        LemmusApplication["LemmusApplication"]:::appHost
        CircuitModule["CircuitModule"]:::appHost
    end

    %% Relationships
    EntryPointActivity -->|"starts"| LemmusApplication
    LemmusApplication -->|"init Hilt & Circuit"| CircuitModule
    CircuitModule -->|"lookup/inject"| DetailPresenter
    CircuitModule -->|"lookup/inject"| HomePresenter
    DetailPresenter -->|"calls"| GetTracks
    HomePresenter -->|"calls"| GetHomeFeed
    GetTracks -->|"implemented by"| GetTracksImpl
    GetHomeFeed -->|"implemented by"| GetHomeFeedImpl
    GetTracksImpl -->|"uses"| RetrofitModule
    GetHomeFeedImpl -->|"uses"| RetrofitModule
    RetrofitModule -->|"requests"| SpotifyAPI
    DetailPresenter -->|"emits state"| AlbumDetailScreen
    HomePresenter -->|"emits state"| CarouselLazyRow
    AlbumDetailScreen -->|"events"| DetailPresenter
    CarouselLazyRow -->|"events"| HomePresenter

    %% Click Events - Infrastructure
    click SongifyRootPlugin "https://github.com/jamesbuhanan/songify/blob/main/build-logic/convention/src/main/kotlin/SongifyRootPlugin.kt"
    click SongifySettingsPlugin "https://github.com/jamesbuhanan/songify/blob/main/build-logic/convention/src/main/kotlin/SongifySettingsPlugin.kt"
    click FocusPlugin "https://github.com/jamesbuhanan/songify/blob/main/build-logic/convention/src/main/kotlin/com/songify/extension/Focus.kt"
    click SettingsGradle "https://github.com/jamesbuhanan/songify/blob/main/settings.gradle"
    click Mkdocs "https://github.com/jamesbuhanan/songify/blob/main/mkdocs.yml"
    click DetektConfig "https://github.com/jamesbuhanan/songify/blob/main/config/detekt/detekt.yml"
    click AffectedModules "https://github.com/jamesbuhanan/songify/blob/main/build-logic/convention/src/main/kotlin/com/songify/extension/AffectedModules.kt"
    click GraphAssert "https://github.com/jamesbuhanan/songify/blob/main/build-logic/convention/src/main/kotlin/com/songify/extension/GraphAssert.kt"

    %% Click Events - App Host
    click EntryPointActivity "https://github.com/jamesbuhanan/songify/blob/main/app/src/main/kotlin/com/songify/app/EntryPointActivity.kt"
    click LemmusApplication "https://github.com/jamesbuhanan/songify/blob/main/app/src/main/kotlin/com/songify/app/LemmusApplication.kt"
    click CircuitModule "https://github.com/jamesbuhanan/songify/blob/main/library/circuit/public/src/main/kotlin/com/songify/library/circuit/di/CircuitModule.kt"
    click HiltPlugin "https://github.com/jamesbuhanan/songify/blob/main/build-logic/convention/src/main/kotlin/com/songify/extension/Hilt.kt"

    %% Click Events - Detail Feature
    click DetailPresenter "https://github.com/jamesbuhanan/songify/blob/main/feature/detail/internal/src/main/kotlin/com/songify/feature/detail/internal/DetailPresenter.kt"
    click DetailContract "https://github.com/jamesbuhanan/songify/blob/main/feature/detail/internal/src/main/kotlin/com/songify/feature/detail/internal/DetailContract.kt"
    click DetailView "https://github.com/jamesbuhanan/songify/blob/main/feature/detail/internal/src/main/kotlin/com/songify/feature/detail/internal/DetailView.kt"
    click DetailScreen "https://github.com/jamesbuhanan/songify/blob/main/feature/detail/public/src/main/kotlin/com/songify/feature/detail/DetailScreen.kt"
    click AlbumDetailScreen "https://github.com/jamesbuhanan/songify/blob/main/feature/detail/internal/src/main/kotlin/com/songify/feature/detail/internal/ui/AlbumDetailScreen.kt"
    click DetailAppModule "https://github.com/jamesbuhanan/songify/blob/main/feature/detail/app/src/main/kotlin/com/songify/feature/premium/app/di/DetailAppModule.kt"

    %% Click Events - Home Feature
    click HomePresenter "https://github.com/jamesbuhanan/songify/blob/main/feature/home/internal/src/main/kotlin/com/songify/feature/home/internal/HomePresenter.kt"
    click HomeContract "https://github.com/jamesbuhanan/songify/blob/main/feature/home/internal/src/main/kotlin/com/songify/feature/home/internal/HomeContract.kt"
    click HomeView "https://github.com/jamesbuhanan/songify/blob/main/feature/home/internal/src/main/kotlin/com/songify/feature/home/internal/HomeView.kt"
    click HomeScreen "https://github.com/jamesbuhanan/songify/blob/main/feature/home/public/src/main/kotlin/com/songify/feature/home/HomeScreen.kt"
    click CarouselLazyRow "https://github.com/jamesbuhanan/songify/blob/main/feature/home/internal/src/main/kotlin/com/songify/feature/home/internal/ui/CarouselLazyRow.kt"
    click HomeAppModule "https://github.com/jamesbuhanan/songify/blob/main/feature/home/app/src/main/kotlin/com/songify/feature/home/app/di/HomeAppModule.kt"

    %% Click Events - Library Public
    click GetTracks "https://github.com/jamesbuhanan/songify/blob/main/library/detail/public/src/main/kotlin/com/songify/library/detail/usecase/GetTracks.kt"
    click GetHomeFeed "https://github.com/jamesbuhanan/songify/blob/main/library/home/public/src/main/kotlin/com/songify/library/home/usecase/GetHomeFeed.kt"
    click GetGenres "https://github.com/jamesbuhanan/songify/blob/main/library/search/public/src/main/kotlin/com/songify/library/genre/usecase/GetGenres.kt"
    click GetPremiumPlans "https://github.com/jamesbuhanan/songify/blob/main/library/premium/public/src/main/kotlin/com/songify/library/premium/usecase/GetPremiumPlans.kt"
    click SongifySession "https://github.com/jamesbuhanan/songify/blob/main/library/session/public/src/main/kotlin/com/songify/library/session/SongifySession.kt"
    click GetNewReleases "https://github.com/jamesbuhanan/songify/blob/main/library/spotify/public/src/main/kotlin/com/songify/library/spotify/usecase/GetNewReleases.kt"

    %% Click Events - Library Internal
    click GetTracksImpl "https://github.com/jamesbuhanan/songify/blob/main/library/detail/internal/src/main/kotlin/com/songify/library/detail/internal/usecase/GetTracksImpl.kt"
    click GetGenresImpl "https://github.com/jamesbuhanan/songify/blob/main/library/search/internal/src/main/kotlin/com/songify/library/genre/internal/usecase/GetGenresImpl.kt"
    click GetPremiumPlansImpl "https://github.com/jamesbuhanan/songify/blob/main/library/premium/internal/src/main/kotlin/com/songify/library/premium/internal/usecase/GetPremiumPlansImpl.kt"
    click GetNewReleasesImpl "https://github.com/jamesbuhanan/songify/blob/main/library/spotify/internal/src/main/kotlin/com/songify/library/spotify/internal/usecase/GetNewReleasesImpl.kt"
    click RetrofitModule "https://github.com/jamesbuhanan/songify/blob/main/library/retrofit/public/src/main/kotlin/com/songify/library/retrofit/di/RetrofitModule.kt"

    %% Legend
    subgraph Legend
        direction TB
        Feature["Feature Module"]:::feature
        PublicLib["Public Library"]:::publicLib
        InternalLib["Internal Library"]:::internalLib
        AppHost["App Host"]:::appHost
        External["External API"]:::external
        Infrastructure["Build/CI Tools"]:::infras
    end

    classDef feature fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef publicLib fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef internalLib fill:#80deea,stroke:#006064,color:#006064;
    classDef appHost fill:#ffe0b2,stroke:#ef6c00,color:#ef6c00;
    classDef external fill:#cfd8dc,stroke:#455a64,color:#455a64,stroke-width:2px,shape:cylinder;
    classDef infras fill:#eceff1,stroke:#607d8b,color:#37474f,stroke-dasharray: 5 5;
    classDef default stroke:#333,stroke-width:1px;
```
