# lyssadev/spotilol architecture

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

- Interactive diagram: https://gitdiagram.com/lyssadev/spotilol
- Repository: https://github.com/lyssadev/spotilol

## Overview

Spotilol is an Android WebView wrapper for Spotify, adding ad/telemetry blocking, playback integrations, account profiles, and optional offline downloads sourced from YouTube Music/InnerTube. The primary path is user → Android app/WebView → Spotify player, with injected controls and a JavaScript bridge connecting page behavior to Android services. Separate branches cover media controls, offline search/download/playback, profiles, and optional proxying. The README documents these capabilities; sampled excerpts support the WebView, download, profile, notification, and proxy components, while some subsystem wiring is represented only where documented.

Main entry points: [`app/src/main/java/com/project/lol/ui/MainActivity.kt`](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/MainActivity.kt) (Main Activity), [`app/src/main/java/com/project/lol/ui/screens/OfflineScreen.kt`](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/screens/OfflineScreen.kt) (Offline Screens), [`app/src/main/java/com/project/lol/offline/DownloadManager.kt`](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/offline/DownloadManager.kt) (Download Manager), [`app/src/main/java/com/project/lol/webview/SpotifyWebViewClient.kt`](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/webview/SpotifyWebViewClient.kt) (WebView Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_player["Spotify Player"]
  node_main["Main Activity<br/>[MainActivity.kt]"]
  node_webclient["WebView Client"]
  node_injections["Player Injections<br/>[PlayerCore.kt]"]
  node_bridge["Spotify Bridge<br/>[SpotifyBridge.kt]"]
end

subgraph group_offline["Offline Audio"]
  node_offlineui["Offline Screens<br/>[OfflineScreen.kt]"]
  node_downloadservice["Download Service<br/>[DownloadService.kt]"]
  node_downloads["Download Manager<br/>[DownloadManager.kt]"]
  node_files[("Offline Store<br/>[OfflineStore.kt]")]
  node_offlineplay["Offline Playback"]
end

subgraph group_android["Android Integration"]
  node_notifications["Media Controls"]
  node_androidauto["Android Auto"]
end

subgraph group_network["Network Services"]
  node_inner["InnerTube Client<br/>[InnerTube.kt]"]
  node_proxy["Local Proxy"]
end

subgraph group_account["Accounts and Settings"]
  node_profiles["Profile Manager<br/>[ProfileManager.kt]"]
  node_prefs[("App Preferences<br/>[SettingsScreen.kt]")]
end

node_user(("Listener"))
node_spotify["Spotify Web Player"]
node_youtube["YouTube Music"]
node_spotifyweb["Spotify WebView"]

node_user -->|"opens and controls"| node_main
node_main -->|"hosts"| node_spotifyweb
node_spotifyweb -->|"loads player"| node_spotify
node_webclient -->|"handles page events"| node_spotifyweb
node_webclient -->|"injects scripts"| node_injections
node_injections -->|"calls native bridge"| node_bridge
node_spotify -->|"sends page events"| node_bridge
node_main -->|"configures"| node_webclient
node_main -->|"manages sessions"| node_profiles
node_profiles -->|"applies cookies"| node_spotifyweb
node_main -->|"starts media controls"| node_notifications
node_notifications -->|"dispatches playback commands"| node_spotifyweb
node_androidauto -->|"browses media"| node_notifications
node_user -->|"requests downloads"| node_offlineui
node_offlineui -->|"starts jobs"| node_downloadservice
node_downloadservice -->|"runs downloads"| node_downloads
node_downloads -->|"requests audio"| node_inner
node_inner -->|"queries and fetches"| node_youtube
node_downloads -->|"saves tracks"| node_files
node_offlineui -->|"lists downloads"| node_files
node_offlineui -->|"starts offline playback"| node_offlineplay
node_offlineplay -->|"reads tracks"| node_files
node_main -->|"reads settings"| node_prefs
node_main -.->|"configures optional proxy"| node_proxy
node_proxy -.->|"proxies traffic"| node_spotifyweb

click node_main "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/MainActivity.kt"
click node_webclient "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/webview/SpotifyWebViewClient.kt"
click node_injections "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/webview/injections/PlayerCore.kt"
click node_bridge "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/bridge/SpotifyBridge.kt"
click node_notifications "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/MediaNotificationService.kt"
click node_offlineui "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/screens/OfflineScreen.kt"
click node_downloadservice "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/DownloadService.kt"
click node_downloads "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/offline/DownloadManager.kt"
click node_inner "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/innertube/InnerTube.kt"
click node_files "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/offline/OfflineStore.kt"
click node_offlineplay "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/OfflineMediaService.kt"
click node_profiles "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/profile/ProfileManager.kt"
click node_proxy "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/proxy/LocalProxyManager.kt"
click node_androidauto "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/MediaNotificationService.kt"
click node_prefs "https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/screens/SettingsScreen.kt"

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_main,node_webclient,node_injections,node_bridge,node_spotifyweb toneBlue
class node_offlineui,node_downloadservice,node_downloads,node_files,node_offlineplay toneAmber
class node_notifications,node_androidauto toneMint
class node_inner,node_proxy toneRose
class node_profiles,node_prefs,node_user,node_spotify,node_youtube toneIndigo
```

## Components

### Spotify Player

- [Main Activity](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/MainActivity.kt): `app/src/main/java/com/project/lol/ui/MainActivity.kt`
- [WebView Client](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/webview/SpotifyWebViewClient.kt): `app/src/main/java/com/project/lol/webview/SpotifyWebViewClient.kt`
- [Player Injections](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/webview/injections/PlayerCore.kt): `app/src/main/java/com/project/lol/webview/injections/PlayerCore.kt`
- [Spotify Bridge](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/bridge/SpotifyBridge.kt): `app/src/main/java/com/project/lol/bridge/SpotifyBridge.kt`

### Offline Audio

- [Offline Screens](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/screens/OfflineScreen.kt): `app/src/main/java/com/project/lol/ui/screens/OfflineScreen.kt`
- [Download Service](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/DownloadService.kt): `app/src/main/java/com/project/lol/service/DownloadService.kt`
- [Download Manager](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/offline/DownloadManager.kt): `app/src/main/java/com/project/lol/offline/DownloadManager.kt`
- [Offline Store](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/offline/OfflineStore.kt): `app/src/main/java/com/project/lol/offline/OfflineStore.kt`
- [Offline Playback](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/OfflineMediaService.kt): `app/src/main/java/com/project/lol/service/OfflineMediaService.kt`

### Android Integration

- [Media Controls](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/MediaNotificationService.kt): `app/src/main/java/com/project/lol/service/MediaNotificationService.kt`
- [Android Auto](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/service/MediaNotificationService.kt): `app/src/main/java/com/project/lol/service/MediaNotificationService.kt`

### Network Services

- [InnerTube Client](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/innertube/InnerTube.kt): `app/src/main/java/com/project/lol/innertube/InnerTube.kt`
- [Local Proxy](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/proxy/LocalProxyManager.kt): `app/src/main/java/com/project/lol/proxy/LocalProxyManager.kt`

### Accounts and Settings

- [Profile Manager](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/profile/ProfileManager.kt): `app/src/main/java/com/project/lol/profile/ProfileManager.kt`
- [App Preferences](https://github.com/lyssadev/spotilol/blob/main/app/src/main/java/com/project/lol/ui/screens/SettingsScreen.kt): `app/src/main/java/com/project/lol/ui/screens/SettingsScreen.kt`

### Other components

- **Listener**
- **Spotify Web Player**
- **YouTube Music**
- **Spotify WebView**

## Connections

- Listener → Main Activity: opens and controls
- Main Activity → Spotify WebView: hosts
- Spotify WebView → Spotify Web Player: loads player
- WebView Client → Spotify WebView: handles page events
- WebView Client → Player Injections: injects scripts
- Player Injections → Spotify Bridge: calls native bridge
- Spotify Web Player → Spotify Bridge: sends page events
- Main Activity → WebView Client: configures
- Main Activity → Profile Manager: manages sessions
- Profile Manager → Spotify WebView: applies cookies
- Main Activity → Media Controls: starts media controls
- Media Controls → Spotify WebView: dispatches playback commands
- Android Auto → Media Controls: browses media
- Listener → Offline Screens: requests downloads
- Offline Screens → Download Service: starts jobs
- Download Service → Download Manager: runs downloads
- Download Manager → InnerTube Client: requests audio
- InnerTube Client → YouTube Music: queries and fetches
- Download Manager → Offline Store: saves tracks
- Offline Screens → Offline Store: lists downloads
- Offline Screens → Offline Playback: starts offline playback
- Offline Playback → Offline Store: reads tracks
- Main Activity → App Preferences: reads settings
- Main Activity → Local Proxy: configures optional proxy
- Local Proxy → Spotify WebView: proxies traffic