# jay6780/pulsewave architecture

> Architecture diagram of the GitHub repository jay6780/pulsewave, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jay6780/pulsewave
- Repository: https://github.com/jay6780/pulsewave

## Overview

PulseWave is an Android music player for discovering, searching, playing, and downloading music, with favorites and synchronized lyrics. The visible search flow dispatches track and artist queries to presenters, then routes selected results to video playback or artist details. Playback state and background controls are represented by the player activities, service, and shared player state. The README documents additional capabilities whose complete wiring is not sampled; those branches are shown conservatively, and unsampled relationships are dashed with no evidence path.

Main entry points: [`app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java`](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java) (Search screen), [`app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java`](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java) (Artist details), [`app/src/main/java/com/yt/downloader/spogify/Service/PlaybackService.java`](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Service/PlaybackService.java) (Playback service), [`app/src/main/java/com/yt/downloader/spogify/mvp/presenter/LyricsPresenter.java`](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/mvp/presenter/LyricsPresenter.java) (Live lyrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery"]
  node_home["Home feed<br/>[HomeFragment.java]"]
  node_search["Search screen"]
  node_search_presenters["Search presenters"]
  node_artist_presenter["Artist presenter"]
  node_track_detail["Artist details"]
end

subgraph group_playback["Playback"]
  node_video_watch["Video playback"]
  node_mini_player["Player controls"]
  node_playback_service["Playback service"]
  node_player_state["Player state<br/>[PlayerState.java]"]
  node_local_audio["Local audio"]
end

subgraph group_library["Library"]
  node_downloads["Offline downloads"]
  node_file_extractor["Downloaded files"]
  node_favorites[("Favorites store")]
  node_queue[("Queue store")]
end

subgraph group_lyrics["Lyrics"]
  node_lyrics_ui["Live lyrics"]
  node_karaoke["Lyrics display"]
  node_lyrics_parse["LRC parser<br/>[LrcParser.java]"]
  node_lyrics_store[("Lyrics store")]
end

subgraph group_network["Networking"]
  node_youtube_api["YouTube API adapter"]
  node_artist_api["Artist image lookup"]
end

node_listener(("Listener"))

node_listener -.->|"browses"| node_home
node_listener -.->|"searches"| node_search
node_search -->|"requests tracks"| node_search_presenters
node_search -->|"requests artists"| node_artist_presenter
node_search -->|"opens artist"| node_track_detail
node_search -->|"opens track"| node_video_watch
node_search_presenters -.->|"fetches results"| node_youtube_api
node_artist_presenter -.->|"looks up artist"| node_artist_api
node_listener -.->|"plays music"| node_video_watch
node_mini_player -.->|"controls playback"| node_playback_service
node_playback_service -->|"stops audio"| node_local_audio
node_playback_service -->|"restores state"| node_player_state
node_listener -.->|"downloads tracks"| node_downloads
node_track_detail -->|"downloads track"| node_downloads
node_track_detail -->|"lists files"| node_file_extractor
node_track_detail -->|"reads favorites"| node_favorites
node_track_detail -->|"uses queue"| node_queue
node_listener -.->|"manages favorites"| node_favorites
node_listener -.->|"views lyrics"| node_lyrics_ui
node_lyrics_ui -.->|"updates display"| node_karaoke
node_karaoke -->|"uses parsed lines"| node_lyrics_parse
node_lyrics_ui -.->|"loads lyrics"| node_lyrics_store

click node_home "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/fragment/HomeFragment.java"
click node_search "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java"
click node_search_presenters "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/mvp/presenter/MusicListPresenter.java"
click node_artist_presenter "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/mvp/presenter/SearchArtistPresenter.java"
click node_track_detail "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java"
click node_video_watch "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/activity/VideoWatchActivity.java"
click node_mini_player "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/activity/MiniPlayerActivity.java"
click node_playback_service "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Service/PlaybackService.java"
click node_player_state "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/PlayerState.java"
click node_local_audio "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/LocalAudioPlayer.java"
click node_downloads "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/download/DownloadTrackModel.java"
click node_file_extractor "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/fileUtils/FilesExtractor.java"
click node_favorites "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/db/FavoriteDatabaseHelper.java"
click node_queue "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/db/QueueDatabaseHelper.java"
click node_lyrics_ui "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/mvp/presenter/LyricsPresenter.java"
click node_karaoke "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/KaraokeLyricsController.java"
click node_lyrics_parse "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/LrcParser.java"
click node_lyrics_store "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/db/LyricsDatabaseHelper.java"
click node_youtube_api "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Retrofit/YoutubeDownloaderAdapter.java"
click node_artist_api "https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/Image/DeezerApiArtist.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_search,node_search_presenters,node_artist_presenter,node_track_detail toneBlue
class node_video_watch,node_mini_player,node_playback_service,node_player_state,node_local_audio toneAmber
class node_downloads,node_file_extractor,node_favorites,node_queue toneMint
class node_lyrics_ui,node_karaoke,node_lyrics_parse,node_lyrics_store toneRose
class node_youtube_api,node_artist_api,node_listener toneIndigo
```

## Components

### Discovery

- [Home feed](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/fragment/HomeFragment.java): `app/src/main/java/com/yt/downloader/spogify/ui/fragment/HomeFragment.java`
- [Search screen](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java): `app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java`
- [Search presenters](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/mvp/presenter/MusicListPresenter.java): `app/src/main/java/com/yt/downloader/spogify/mvp/presenter/MusicListPresenter.java`
- [Artist presenter](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/mvp/presenter/SearchArtistPresenter.java): `app/src/main/java/com/yt/downloader/spogify/mvp/presenter/SearchArtistPresenter.java`
- [Artist details](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java): `app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java`

### Playback

- [Video playback](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/activity/VideoWatchActivity.java): `app/src/main/java/com/yt/downloader/spogify/ui/activity/VideoWatchActivity.java`
- [Player controls](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/ui/activity/MiniPlayerActivity.java): `app/src/main/java/com/yt/downloader/spogify/ui/activity/MiniPlayerActivity.java`
- [Playback service](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Service/PlaybackService.java): `app/src/main/java/com/yt/downloader/spogify/Service/PlaybackService.java`
- [Player state](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/PlayerState.java): `app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/PlayerState.java`
- [Local audio](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/LocalAudioPlayer.java): `app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/LocalAudioPlayer.java`

### Library

- [Offline downloads](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/download/DownloadTrackModel.java): `app/src/main/java/com/yt/downloader/spogify/Utils/download/DownloadTrackModel.java`
- [Downloaded files](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/fileUtils/FilesExtractor.java): `app/src/main/java/com/yt/downloader/spogify/Utils/fileUtils/FilesExtractor.java`
- [Favorites store](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/db/FavoriteDatabaseHelper.java): `app/src/main/java/com/yt/downloader/spogify/Utils/db/FavoriteDatabaseHelper.java`
- [Queue store](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/db/QueueDatabaseHelper.java): `app/src/main/java/com/yt/downloader/spogify/Utils/db/QueueDatabaseHelper.java`

### Lyrics

- [Live lyrics](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/mvp/presenter/LyricsPresenter.java): `app/src/main/java/com/yt/downloader/spogify/mvp/presenter/LyricsPresenter.java`
- [Lyrics display](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/KaraokeLyricsController.java): `app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/KaraokeLyricsController.java`
- [LRC parser](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/LrcParser.java): `app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/LrcParser.java`
- [Lyrics store](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/db/LyricsDatabaseHelper.java): `app/src/main/java/com/yt/downloader/spogify/Utils/db/LyricsDatabaseHelper.java`

### Networking

- [YouTube API adapter](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Retrofit/YoutubeDownloaderAdapter.java): `app/src/main/java/com/yt/downloader/spogify/Retrofit/YoutubeDownloaderAdapter.java`
- [Artist image lookup](https://github.com/jay6780/pulsewave/blob/master/app/src/main/java/com/yt/downloader/spogify/Utils/Image/DeezerApiArtist.java): `app/src/main/java/com/yt/downloader/spogify/Utils/Image/DeezerApiArtist.java`

### Other components

- **Listener**

## Connections

- Listener → Home feed: browses
- Listener → Search screen: searches
- Search screen → Search presenters: requests tracks (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java`)
- Search screen → Artist presenter: requests artists (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java`)
- Search screen → Artist details: opens artist (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java`)
- Search screen → Video playback: opens track (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/fragment/SearchFragment.java`)
- Search presenters → YouTube API adapter: fetches results
- Artist presenter → Artist image lookup: looks up artist
- Listener → Video playback: plays music
- Player controls → Playback service: controls playback (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/activity/MiniPlayerActivity.java`)
- Playback service → Local audio: stops audio (evidence: `app/src/main/java/com/yt/downloader/spogify/Service/PlaybackService.java`)
- Playback service → Player state: restores state (evidence: `app/src/main/java/com/yt/downloader/spogify/Service/PlaybackService.java`)
- Listener → Offline downloads: downloads tracks
- Artist details → Offline downloads: downloads track (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java`)
- Artist details → Downloaded files: lists files (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java`)
- Artist details → Favorites store: reads favorites (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java`)
- Artist details → Queue store: uses queue (evidence: `app/src/main/java/com/yt/downloader/spogify/ui/activity/TrackInfoActivity.java`)
- Listener → Favorites store: manages favorites
- Listener → Live lyrics: views lyrics
- Live lyrics → Lyrics display: updates display
- Lyrics display → LRC parser: uses parsed lines (evidence: `app/src/main/java/com/yt/downloader/spogify/Utils/lyrics/KaraokeLyricsController.java`)
- Live lyrics → Lyrics store: loads lyrics
