# salmee12/suradda-app architecture

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

- Interactive diagram: https://gitdiagram.com/salmee12/suradda-app
- Repository: https://github.com/salmee12/suradda-app

## Overview

SurAdda is a Flutter social-music app. Users authenticate, browse cloud or device music, and play through a persistent shared player; they can also create or join synchronized online parties or nearby hotspot parties. The map follows the documented MVVM/data/service layers and preserves authentication, subscription awareness, social, radio, and download capabilities. Relationships are based on README statements and structure; most Dart source was not sampled, so implementation-specific calls are not asserted.

Main entry points: [`lib/services/audio/playback_service.dart`](https://github.com/salmee12/suradda-app/blob/master/lib/services/audio/playback_service.dart) (Shared playback), [`lib/presentation/viewmodels/hotspot_room_viewmodel.dart`](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/hotspot_room_viewmodel.dart) (Hotspot party), [`lib/presentation/viewmodels/auth_viewmodel.dart`](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/auth_viewmodel.dart) (Authentication), [`lib/presentation/views`](https://github.com/salmee12/suradda-app/tree/master/lib/presentation/views) (Feature screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_entry["App entry<br/>[main.dart]"]
  node_shell["App shell<br/>[app.dart]"]
  node_screens["Feature screens"]
  node_viewmodels["Feature state"]
  node_navigation["Navigation<br/>[app_router.dart]"]
end

subgraph group_music["Music playback"]
  node_cloud_library["Cloud library"]
  node_local_library["Device library"]
  node_catalogue["Song catalogue<br/>[song_api.dart]"]
  node_track["Playable track"]
  node_playback["Shared playback"]
  node_cloud_audio["Cloud audio"]
  node_device_audio["Device audio"]
  node_player["Player UI"]
  node_radio["Radio<br/>[radio_service.dart]"]
  node_downloads["Song downloads"]
end

subgraph group_parties["Listening parties"]
  node_online_party["Online party"]
  node_online_sync["Online sync"]
  node_hotspot_party["Hotspot party"]
  node_hotspot_host["Hotspot host"]
  node_hotspot_client["Hotspot client"]
end

subgraph group_identity["Identity and social"]
  node_auth["Authentication"]
  node_auth_api["Auth API<br/>[auth_api.dart]"]
  node_tokens[("Token storage")]
  node_friends["Friends and streaks"]
end

node_listener(("Listener"))
node_backend{{"SurAdda backend"}}

node_listener -->|"opens"| node_entry
node_entry -->|"starts"| node_shell
node_shell -->|"shows"| node_screens
node_screens -->|"uses state"| node_viewmodels
node_screens -->|"navigates"| node_navigation
node_listener -->|"browses"| node_cloud_library
node_listener -->|"browses"| node_local_library
node_cloud_library -->|"loads catalogue"| node_catalogue
node_catalogue -->|"requests songs"| node_backend
node_cloud_library -->|"provides track"| node_track
node_local_library -->|"provides track"| node_track
node_track -->|"plays"| node_playback
node_playback -->|"plays cloud"| node_cloud_audio
node_playback -->|"plays local"| node_device_audio
node_player -->|"controls"| node_playback
node_listener -->|"joins or hosts"| node_online_party
node_online_party -->|"synchronizes"| node_online_sync
node_online_sync -->|"syncs online"| node_backend
node_online_party -->|"mirrors host"| node_playback
node_listener -->|"joins or hosts"| node_hotspot_party
node_hotspot_party -->|"serves local audio"| node_hotspot_host
node_hotspot_party -->|"discovers host"| node_hotspot_client
node_hotspot_party -->|"synchronizes"| node_playback
node_listener -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_auth_api
node_auth_api -->|"sends credentials"| node_backend
node_auth -->|"persists tokens"| node_tokens
node_auth -->|"refreshes tokens"| node_backend
node_listener -->|"uses social features"| node_friends
node_listener -->|"listens to radio"| node_radio
node_listener -->|"downloads songs"| node_downloads
node_listener -.->|"checks subscription"| node_backend

click node_entry "https://github.com/salmee12/suradda-app/blob/master/lib/main.dart"
click node_shell "https://github.com/salmee12/suradda-app/blob/master/lib/app.dart"
click node_screens "https://github.com/salmee12/suradda-app/tree/master/lib/presentation/views"
click node_viewmodels "https://github.com/salmee12/suradda-app/tree/master/lib/presentation/viewmodels"
click node_navigation "https://github.com/salmee12/suradda-app/blob/master/lib/core/routes/app_router.dart"
click node_cloud_library "https://github.com/salmee12/suradda-app/blob/master/lib/presentation/views/library/cloud_songs_tab.dart"
click node_local_library "https://github.com/salmee12/suradda-app/blob/master/lib/presentation/views/library/local_songs_tab.dart"
click node_catalogue "https://github.com/salmee12/suradda-app/blob/master/lib/data/datasources/remote/song_api.dart"
click node_track "https://github.com/salmee12/suradda-app/blob/master/lib/data/models/playable_track.dart"
click node_playback "https://github.com/salmee12/suradda-app/blob/master/lib/services/audio/playback_service.dart"
click node_cloud_audio "https://github.com/salmee12/suradda-app/blob/master/lib/services/audio/cloud_audio_service.dart"
click node_device_audio "https://github.com/salmee12/suradda-app/blob/master/lib/services/audio/local_audio_service.dart"
click node_player "https://github.com/salmee12/suradda-app/blob/master/lib/presentation/views/player/music_player_page.dart"
click node_online_party "https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/online_room_viewmodel.dart"
click node_online_sync "https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/online_room_socket_service.dart"
click node_hotspot_party "https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/hotspot_room_viewmodel.dart"
click node_hotspot_host "https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/local_stream_host_service.dart"
click node_hotspot_client "https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/local_stream_client_service.dart"
click node_auth "https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/auth_viewmodel.dart"
click node_auth_api "https://github.com/salmee12/suradda-app/blob/master/lib/data/datasources/remote/auth_api.dart"
click node_tokens "https://github.com/salmee12/suradda-app/blob/master/lib/services/auth/token_storage_service.dart"
click node_friends "https://github.com/salmee12/suradda-app/blob/master/lib/services/social/friend_service.dart"
click node_radio "https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/radio_service.dart"
click node_downloads "https://github.com/salmee12/suradda-app/blob/master/lib/services/download/song_download_service.dart"

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_entry,node_shell,node_screens,node_viewmodels,node_navigation toneBlue
class node_cloud_library,node_local_library,node_catalogue,node_track,node_playback,node_cloud_audio,node_device_audio,node_player,node_radio,node_downloads toneAmber
class node_online_party,node_online_sync,node_hotspot_party,node_hotspot_host,node_hotspot_client toneMint
class node_auth,node_auth_api,node_tokens,node_friends toneRose
class node_listener,node_backend toneIndigo
```

## Components

### App shell

- [App entry](https://github.com/salmee12/suradda-app/blob/master/lib/main.dart): `lib/main.dart`
- [App shell](https://github.com/salmee12/suradda-app/blob/master/lib/app.dart): `lib/app.dart`
- [Feature screens](https://github.com/salmee12/suradda-app/tree/master/lib/presentation/views): `lib/presentation/views`
- [Feature state](https://github.com/salmee12/suradda-app/tree/master/lib/presentation/viewmodels): `lib/presentation/viewmodels`
- [Navigation](https://github.com/salmee12/suradda-app/blob/master/lib/core/routes/app_router.dart): `lib/core/routes/app_router.dart`

### Music playback

- [Cloud library](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/views/library/cloud_songs_tab.dart): `lib/presentation/views/library/cloud_songs_tab.dart`
- [Device library](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/views/library/local_songs_tab.dart): `lib/presentation/views/library/local_songs_tab.dart`
- [Song catalogue](https://github.com/salmee12/suradda-app/blob/master/lib/data/datasources/remote/song_api.dart): `lib/data/datasources/remote/song_api.dart`
- [Playable track](https://github.com/salmee12/suradda-app/blob/master/lib/data/models/playable_track.dart): `lib/data/models/playable_track.dart`
- [Shared playback](https://github.com/salmee12/suradda-app/blob/master/lib/services/audio/playback_service.dart): `lib/services/audio/playback_service.dart`
- [Cloud audio](https://github.com/salmee12/suradda-app/blob/master/lib/services/audio/cloud_audio_service.dart): `lib/services/audio/cloud_audio_service.dart`
- [Device audio](https://github.com/salmee12/suradda-app/blob/master/lib/services/audio/local_audio_service.dart): `lib/services/audio/local_audio_service.dart`
- [Player UI](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/views/player/music_player_page.dart): `lib/presentation/views/player/music_player_page.dart`
- [Radio](https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/radio_service.dart): `lib/services/streaming/radio_service.dart`
- [Song downloads](https://github.com/salmee12/suradda-app/blob/master/lib/services/download/song_download_service.dart): `lib/services/download/song_download_service.dart`

### Listening parties

- [Online party](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/online_room_viewmodel.dart): `lib/presentation/viewmodels/online_room_viewmodel.dart`
- [Online sync](https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/online_room_socket_service.dart): `lib/services/streaming/online_room_socket_service.dart`
- [Hotspot party](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/hotspot_room_viewmodel.dart): `lib/presentation/viewmodels/hotspot_room_viewmodel.dart`
- [Hotspot host](https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/local_stream_host_service.dart): `lib/services/streaming/local_stream_host_service.dart`
- [Hotspot client](https://github.com/salmee12/suradda-app/blob/master/lib/services/streaming/local_stream_client_service.dart): `lib/services/streaming/local_stream_client_service.dart`

### Identity and social

- [Authentication](https://github.com/salmee12/suradda-app/blob/master/lib/presentation/viewmodels/auth_viewmodel.dart): `lib/presentation/viewmodels/auth_viewmodel.dart`
- [Auth API](https://github.com/salmee12/suradda-app/blob/master/lib/data/datasources/remote/auth_api.dart): `lib/data/datasources/remote/auth_api.dart`
- [Token storage](https://github.com/salmee12/suradda-app/blob/master/lib/services/auth/token_storage_service.dart): `lib/services/auth/token_storage_service.dart`
- [Friends and streaks](https://github.com/salmee12/suradda-app/blob/master/lib/services/social/friend_service.dart): `lib/services/social/friend_service.dart`

### Other components

- **Listener**
- **SurAdda backend**

## Connections

- Listener → App entry: opens (evidence: `README.md`)
- App entry → App shell: starts (evidence: `README.md`)
- App shell → Feature screens: shows (evidence: `README.md`)
- Feature screens → Feature state: uses state (evidence: `README.md`)
- Feature screens → Navigation: navigates (evidence: `README.md`)
- Listener → Cloud library: browses (evidence: `README.md`)
- Listener → Device library: browses (evidence: `README.md`)
- Cloud library → Song catalogue: loads catalogue (evidence: `README.md`)
- Song catalogue → SurAdda backend: requests songs (evidence: `README.md`)
- Cloud library → Playable track: provides track (evidence: `README.md`)
- Device library → Playable track: provides track (evidence: `README.md`)
- Playable track → Shared playback: plays (evidence: `README.md`)
- Shared playback → Cloud audio: plays cloud (evidence: `README.md`)
- Shared playback → Device audio: plays local (evidence: `README.md`)
- Player UI → Shared playback: controls (evidence: `README.md`)
- Listener → Online party: joins or hosts (evidence: `README.md`)
- Online party → Online sync: synchronizes (evidence: `README.md`)
- Online sync → SurAdda backend: syncs online (evidence: `README.md`)
- Online party → Shared playback: mirrors host (evidence: `README.md`)
- Listener → Hotspot party: joins or hosts (evidence: `README.md`)
- Hotspot party → Hotspot host: serves local audio (evidence: `README.md`)
- Hotspot party → Hotspot client: discovers host (evidence: `README.md`)
- Hotspot party → Shared playback: synchronizes (evidence: `README.md`)
- Listener → Authentication: signs in (evidence: `README.md`)
- Authentication → Auth API: authenticates (evidence: `README.md`)
- Auth API → SurAdda backend: sends credentials (evidence: `README.md`)
- Authentication → Token storage: persists tokens (evidence: `README.md`)
- Authentication → SurAdda backend: refreshes tokens (evidence: `README.md`)
- Listener → Friends and streaks: uses social features (evidence: `README.md`)
- Listener → Radio: listens to radio (evidence: `README.md`)
- Listener → Song downloads: downloads songs (evidence: `README.md`)
- Listener → SurAdda backend: checks subscription (evidence: `README.md`)