# baqir-cs/audiosync architecture

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

- Interactive diagram: https://gitdiagram.com/baqir-cs/audiosync
- Repository: https://github.com/baqir-cs/audiosync

## Overview

Audio Sync TV is an Android TV live-audio player whose central workflow is to load an M3U playlist, choose a commentary stream, and adjust its delay from a phone dashboard hosted on the TV. The foreground service coordinates playback and the local HTTP server; the player maintains the in-memory delay while playlist and last-stream data persist. The repository also includes a TV overlay/remote-control path and a separate license administration backend. The README documents the dashboard and API; its web asset is not present in the supplied tree, so it is represented by the server route rather than a source node.

Main entry points: [`app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt`](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt) (Local HTTP server), [`app/src/main/java/com/audiosync/tv/service/AudioSyncService.kt`](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/AudioSyncService.kt) (Audio service), [`app/src/main/java/com/audiosync/tv/player/ExoPlayerController.kt`](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/player/ExoPlayerController.kt) (Playback and delay), [`app/src/main/java/com/audiosync/tv/service/FloatingHudService.kt`](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/FloatingHudService.kt) (Floating HUD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tv_app["TV app and playback"]
  node_main_activity["TV entry screen<br/>[MainActivity.kt]"]
  node_audio_service["Audio service"]
  node_player["Playback and delay"]
  node_delay_processor["Delay processor"]
end

subgraph group_dashboard["Dashboard and playlists"]
  node_http_server["Local HTTP server<br/>[KtorHttpServer.kt]"]
  node_playlist_repo[("Playlist persistence")]
  node_m3u_parser["M3U parser<br/>[M3UParser.kt]"]
  node_channel_repo["Channel state"]
  node_phone_dashboard["Phone dashboard<br/>[KtorHttpServer.kt]"]
end

subgraph group_remote_ui["TV overlay controls"]
  node_hud_service["Floating HUD"]
  node_key_service["TV key handler"]
end

subgraph group_licensing["License services"]
  node_license_manager["License manager<br/>[LicenseManager.kt]"]
  node_license_crypto["License cryptography"]
  node_license_server["License API<br/>[server.js]"]
end

subgraph group_sports_data["Sports data engine"]
  node_matches_engine["Matches engine<br/>[matches_engine.js]"]
end

node_phone_user(("Phone user"))
node_tv_video(("IPTV video"))
node_stream_source(("Audio stream"))
node_m3u_source(("M3U source"))
node_license_cloud["License cloud"]
node_admin_user(("License administrator"))
node_sports_sources(("Sports data sources"))

node_phone_user -->|"opens"| node_phone_dashboard
node_main_activity -->|"starts"| node_audio_service
node_main_activity -->|"shows QR for"| node_phone_dashboard
node_phone_dashboard -->|"sends API requests"| node_http_server
node_http_server -->|"dispatches controls"| node_audio_service
node_http_server -->|"parses playlist"| node_m3u_parser
node_http_server -->|"loads and saves"| node_playlist_repo
node_http_server -->|"updates channels"| node_channel_repo
node_audio_service -->|"loads saved streams"| node_playlist_repo
node_audio_service -->|"controls playback"| node_player
node_player -->|"plays stream"| node_stream_source
node_player -->|"processes delayed audio"| node_delay_processor
node_tv_video -.->|"is aligned with"| node_phone_user
node_m3u_source -->|"provides playlist URL"| node_http_server
node_key_service -->|"toggles HUD"| node_hud_service
node_hud_service -->|"dispatches stream and delay controls"| node_audio_service
node_hud_service -->|"observes license state"| node_license_manager
node_license_manager -->|"verifies device and signature"| node_license_crypto
node_license_manager -->|"syncs license status"| node_license_server
node_admin_user -->|"manages licenses"| node_license_server
node_matches_engine -.->|"scrapes and integrates"| node_sports_sources

click node_main_activity "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/MainActivity.kt"
click node_audio_service "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/AudioSyncService.kt"
click node_player "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/player/ExoPlayerController.kt"
click node_delay_processor "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/player/DelayLineAudioProcessor.kt"
click node_http_server "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt"
click node_playlist_repo "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/data/PlaylistRepository.kt"
click node_m3u_parser "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/data/M3UParser.kt"
click node_channel_repo "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/data/ChannelRepository.kt"
click node_phone_dashboard "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt"
click node_hud_service "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/FloatingHudService.kt"
click node_key_service "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/TvKeyAccessibilityService.kt"
click node_license_manager "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/license/LicenseManager.kt"
click node_license_crypto "https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/license/CryptoLicenseUtils.kt"
click node_license_server "https://github.com/baqir-cs/audiosync/blob/master/backend/server.js"
click node_matches_engine "https://github.com/baqir-cs/audiosync/blob/master/backend/matches_engine.js"

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_activity,node_audio_service,node_player,node_delay_processor,node_phone_user toneBlue
class node_http_server,node_playlist_repo,node_m3u_parser,node_channel_repo,node_phone_dashboard toneAmber
class node_hud_service,node_key_service toneMint
class node_license_manager,node_license_crypto,node_license_server toneRose
class node_matches_engine,node_tv_video,node_stream_source,node_m3u_source,node_license_cloud,node_admin_user,node_sports_sources toneIndigo
```

## Components

### TV app and playback

- [TV entry screen](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/MainActivity.kt): `app/src/main/java/com/audiosync/tv/MainActivity.kt`
- [Audio service](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/AudioSyncService.kt): `app/src/main/java/com/audiosync/tv/service/AudioSyncService.kt`
- [Playback and delay](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/player/ExoPlayerController.kt): `app/src/main/java/com/audiosync/tv/player/ExoPlayerController.kt`
- [Delay processor](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/player/DelayLineAudioProcessor.kt): `app/src/main/java/com/audiosync/tv/player/DelayLineAudioProcessor.kt`

### Dashboard and playlists

- [Local HTTP server](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt): `app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt`
- [Playlist persistence](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/data/PlaylistRepository.kt): `app/src/main/java/com/audiosync/tv/data/PlaylistRepository.kt`
- [M3U parser](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/data/M3UParser.kt): `app/src/main/java/com/audiosync/tv/data/M3UParser.kt`
- [Channel state](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/data/ChannelRepository.kt): `app/src/main/java/com/audiosync/tv/data/ChannelRepository.kt`
- [Phone dashboard](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt): `app/src/main/java/com/audiosync/tv/server/KtorHttpServer.kt`

### TV overlay controls

- [Floating HUD](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/FloatingHudService.kt): `app/src/main/java/com/audiosync/tv/service/FloatingHudService.kt`
- [TV key handler](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/service/TvKeyAccessibilityService.kt): `app/src/main/java/com/audiosync/tv/service/TvKeyAccessibilityService.kt`

### License services

- [License manager](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/license/LicenseManager.kt): `app/src/main/java/com/audiosync/tv/license/LicenseManager.kt`
- [License cryptography](https://github.com/baqir-cs/audiosync/blob/master/app/src/main/java/com/audiosync/tv/license/CryptoLicenseUtils.kt): `app/src/main/java/com/audiosync/tv/license/CryptoLicenseUtils.kt`
- [License API](https://github.com/baqir-cs/audiosync/blob/master/backend/server.js): `backend/server.js`

### Sports data engine

- [Matches engine](https://github.com/baqir-cs/audiosync/blob/master/backend/matches_engine.js): `backend/matches_engine.js`

### Other components

- **Phone user**
- **IPTV video**
- **Audio stream**
- **M3U source**
- **License cloud**
- **License administrator**
- **Sports data sources**

## Connections

- Phone user → Phone dashboard: opens
- TV entry screen → Audio service: starts
- TV entry screen → Phone dashboard: shows QR for
- Phone dashboard → Local HTTP server: sends API requests
- Local HTTP server → Audio service: dispatches controls
- Local HTTP server → M3U parser: parses playlist
- Local HTTP server → Playlist persistence: loads and saves
- Local HTTP server → Channel state: updates channels
- Audio service → Playlist persistence: loads saved streams
- Audio service → Playback and delay: controls playback
- Playback and delay → Audio stream: plays stream
- Playback and delay → Delay processor: processes delayed audio
- IPTV video → Phone user: is aligned with
- M3U source → Local HTTP server: provides playlist URL
- TV key handler → Floating HUD: toggles HUD
- Floating HUD → Audio service: dispatches stream and delay controls
- Floating HUD → License manager: observes license state
- License manager → License cryptography: verifies device and signature
- License manager → License API: syncs license status
- License administrator → License API: manages licenses
- Matches engine → Sports data sources: scrapes and integrates