# huny4daniel/tape-box_v architecture

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

- Interactive diagram: https://gitdiagram.com/huny4daniel/tape-box_v
- Repository: https://github.com/huny4daniel/tape-box_v

## Overview

Tape Box is a phone-first music collection player: Android owns the library, playback and durable state, while a shared web interface serves both the phone WebView and a PC browser. The PC app discovers and securely relays to the phone, and can also generate synchronized lyrics locally or on phone tracks. The README documents the major user workflows; source excerpts and the SOURCE INDEX support selected internal links. Unsampled implementation details are represented only where the README describes them.

Main entry points: [`android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java`](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java) (Phone web servers), [`android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java`](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java) (Music library), [`android/app/src/main/java/io/github/huny4daniel/musiccollection/Db.java`](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Db.java) (Collection database), [`pc/tape_player.py`](https://github.com/huny4daniel/tape-box_v/blob/main/pc/tape_player.py) (PC player window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Shared web interface"]
  node_webview["Phone WebView<br/>[MainActivity.java]"]
  node_ui["App screens<br/>[app.js]"]
  node_pages["Collection pages<br/>[pages.js]"]
  node_events["UI events<br/>[events.js]"]
  node_api["Phone API client<br/>[api.js]"]
  node_player["Queue and player<br/>[player.js]"]
end

subgraph group_phone["Android phone app"]
  node_phone_server["Phone web servers<br/>[WebServer.java]"]
  node_library["Music library<br/>[Library.java]"]
  node_track["Track model<br/>[Track.java]"]
  node_database[("Collection database<br/>[Db.java]")]
  node_playback["Native playback"]
  node_lyrics_tags["Embedded lyrics<br/>[Id3Lyrics.java]"]
  node_playlist_import["Playlist import"]
  node_playlist_export["Playlist export"]
  node_tls["Phone TLS identity<br/>[TlsCert.java]"]
end

subgraph group_pc["PC companion"]
  node_pc_app["PC player window<br/>[tape_player.py]"]
  node_phone_link["Secure phone link<br/>[phonelink.py]"]
end

subgraph group_lyrics["Lyrics generation"]
  node_lyric_manager["LyricSync manager<br/>[lyricsync.py]"]
  node_lyric_worker["LyricSync worker"]
end

node_phone_user(("Phone user"))
node_pc_user(("PC user"))

node_phone_user -->|"opens app"| node_webview
node_webview -->|"loads shared screen"| node_ui
node_pc_user -->|"starts companion"| node_pc_app
node_pc_app -->|"discovers and relays"| node_phone_link
node_phone_link -->|"connects over HTTPS"| node_phone_server
node_phone_server -->|"uses certificate"| node_tls
node_phone_server -->|"serves shared files"| node_ui
node_ui -->|"shows collection views"| node_pages
node_ui -->|"handles interactions"| node_events
node_events -->|"requests phone data"| node_api
node_api -->|"calls API"| node_phone_server
node_phone_server -->|"serves library data"| node_library
node_library -->|"creates track records"| node_track
node_library -->|"assigns collection metadata"| node_database
node_library -->|"imports playlists on scan"| node_playlist_import
node_library -->|"reads track lyrics"| node_lyrics_tags
node_api -->|"drives queue"| node_player
node_player -->|"sends playback commands"| node_playback
node_playback -->|"records listening"| node_database
node_phone_server -->|"reads and updates state"| node_database
node_phone_server -->|"schedules tape export"| node_playlist_export
node_playlist_export -->|"syncs tape state"| node_database
node_pc_app -->|"manages lyric generation"| node_lyric_manager
node_lyric_manager -->|"runs generation worker"| node_lyric_worker
node_lyric_manager -->|"transfers lyric results"| node_phone_link
node_lyric_worker -.->|"phone mode saves lyrics"| node_database
node_pc_app -->|"uploads pending playlists"| node_phone_server
node_phone_server -->|"imports received playlists"| node_playlist_import

click node_webview "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/MainActivity.java"
click node_ui "https://github.com/huny4daniel/tape-box_v/blob/main/js/app.js"
click node_pages "https://github.com/huny4daniel/tape-box_v/blob/main/js/pages.js"
click node_events "https://github.com/huny4daniel/tape-box_v/blob/main/js/events.js"
click node_api "https://github.com/huny4daniel/tape-box_v/blob/main/js/api.js"
click node_player "https://github.com/huny4daniel/tape-box_v/blob/main/js/player.js"
click node_phone_server "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java"
click node_library "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java"
click node_track "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Track.java"
click node_database "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Db.java"
click node_playback "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaybackService.java"
click node_lyrics_tags "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Id3Lyrics.java"
click node_playlist_import "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaylistImport.java"
click node_playlist_export "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaylistExport.java"
click node_tls "https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/TlsCert.java"
click node_pc_app "https://github.com/huny4daniel/tape-box_v/blob/main/pc/tape_player.py"
click node_phone_link "https://github.com/huny4daniel/tape-box_v/blob/main/pc/phonelink.py"
click node_lyric_manager "https://github.com/huny4daniel/tape-box_v/blob/main/pc/lyricsync.py"
click node_lyric_worker "https://github.com/huny4daniel/tape-box_v/blob/main/pc/lyricsync_worker.py"

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_webview,node_ui,node_pages,node_events,node_api,node_player,node_phone_user,node_pc_user toneBlue
class node_phone_server,node_library,node_track,node_database,node_playback,node_lyrics_tags,node_playlist_import,node_playlist_export,node_tls toneAmber
class node_pc_app,node_phone_link toneMint
class node_lyric_manager,node_lyric_worker toneRose
```

## Components

### Shared web interface

- [Phone WebView](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/MainActivity.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/MainActivity.java`
- [App screens](https://github.com/huny4daniel/tape-box_v/blob/main/js/app.js): `js/app.js`
- [Collection pages](https://github.com/huny4daniel/tape-box_v/blob/main/js/pages.js): `js/pages.js`
- [UI events](https://github.com/huny4daniel/tape-box_v/blob/main/js/events.js): `js/events.js`
- [Phone API client](https://github.com/huny4daniel/tape-box_v/blob/main/js/api.js): `js/api.js`
- [Queue and player](https://github.com/huny4daniel/tape-box_v/blob/main/js/player.js): `js/player.js`

### Android phone app

- [Phone web servers](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java`
- [Music library](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java`
- [Track model](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Track.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/Track.java`
- [Collection database](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Db.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/Db.java`
- [Native playback](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaybackService.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaybackService.java`
- [Embedded lyrics](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/Id3Lyrics.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/Id3Lyrics.java`
- [Playlist import](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaylistImport.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaylistImport.java`
- [Playlist export](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaylistExport.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/PlaylistExport.java`
- [Phone TLS identity](https://github.com/huny4daniel/tape-box_v/blob/main/android/app/src/main/java/io/github/huny4daniel/musiccollection/TlsCert.java): `android/app/src/main/java/io/github/huny4daniel/musiccollection/TlsCert.java`

### PC companion

- [PC player window](https://github.com/huny4daniel/tape-box_v/blob/main/pc/tape_player.py): `pc/tape_player.py`
- [Secure phone link](https://github.com/huny4daniel/tape-box_v/blob/main/pc/phonelink.py): `pc/phonelink.py`

### Lyrics generation

- [LyricSync manager](https://github.com/huny4daniel/tape-box_v/blob/main/pc/lyricsync.py): `pc/lyricsync.py`
- [LyricSync worker](https://github.com/huny4daniel/tape-box_v/blob/main/pc/lyricsync_worker.py): `pc/lyricsync_worker.py`

### Other components

- **Phone user**
- **PC user**

## Connections

- Phone user → Phone WebView: opens app (evidence: `README.md`)
- Phone WebView → App screens: loads shared screen (evidence: `README.md`)
- PC user → PC player window: starts companion (evidence: `README.md`)
- PC player window → Secure phone link: discovers and relays (evidence: `README.md`)
- Secure phone link → Phone web servers: connects over HTTPS (evidence: `README.md`)
- Phone web servers → Phone TLS identity: uses certificate (evidence: `android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java`)
- Phone web servers → App screens: serves shared files (evidence: `README.md`)
- App screens → Collection pages: shows collection views (evidence: `README.md`)
- App screens → UI events: handles interactions (evidence: `README.md`)
- UI events → Phone API client: requests phone data (evidence: `README.md`)
- Phone API client → Phone web servers: calls API (evidence: `README.md`)
- Phone web servers → Music library: serves library data (evidence: `README.md`)
- Music library → Track model: creates track records (evidence: `android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java`)
- Music library → Collection database: assigns collection metadata (evidence: `README.md`)
- Music library → Playlist import: imports playlists on scan (evidence: `android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java`)
- Music library → Embedded lyrics: reads track lyrics (evidence: `android/app/src/main/java/io/github/huny4daniel/musiccollection/Library.java`)
- Phone API client → Queue and player: drives queue (evidence: `README.md`)
- Queue and player → Native playback: sends playback commands (evidence: `README.md`)
- Native playback → Collection database: records listening (evidence: `README.md`)
- Phone web servers → Collection database: reads and updates state (evidence: `android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java`)
- Phone web servers → Playlist export: schedules tape export (evidence: `android/app/src/main/java/io/github/huny4daniel/musiccollection/WebServer.java`)
- Playlist export → Collection database: syncs tape state (evidence: `README.md`)
- PC player window → LyricSync manager: manages lyric generation (evidence: `pc/tape_player.py`)
- LyricSync manager → LyricSync worker: runs generation worker (evidence: `pc/lyricsync.py`)
- LyricSync manager → Secure phone link: transfers lyric results (evidence: `README.md`)
- LyricSync worker → Collection database: phone mode saves lyrics
- PC player window → Phone web servers: uploads pending playlists (evidence: `README.md`)
- Phone web servers → Playlist import: imports received playlists (evidence: `README.md`)