Station scope is explicit
Metadata, Queue, History, Chat, requests, Favorites, activity, and sessions all carry a station identity. State cannot silently leak between stations.
Engineering the player
How the project is built
Development proceeds in evidence-backed vertical slices: research the station contract, define domain boundaries, implement native behavior, validate narrowly, then record the result before moving on.
Dependency direction
Interfaces point inward
Compose never imports network, cookie, WebSocket, ExoPlayer, or station protocol implementations. Screens receive immutable state and emit actions upward; ViewModels depend on domain repository and playback interfaces.
PresentationCompose UIImmutable state · actions upward
State ownerViewModelsCoroutines · station scope
DomainInterfaces + modelsCapabilities · policies · contracts
DataStation adaptersBounded I/O · defensive parsing
PlaybackMedia3 serviceExoPlayer · MediaSession
Design principles
Constraints that keep the app trustworthy
Capabilities replace assumptions
A feature appears only when the station contract says it is supported. Missing evidence produces an unavailable or unknown state, never invented behavior.
Remote traffic is bounded
Polling intervals, response sizes, row counts, character limits, same-origin rules, and redirect policies are enforced by the data layer.
Mutations are deliberate
Chat, song requests, request messages, and abuse reports require explicit user actions and are not retried automatically when the result is indeterminate.
Secrets stay outside Git
Credentials, cookies, CSRF values, signing material, reviewer accounts, HAR files, and unsanitized captures never belong in repository history.
Native remains native
App features use Compose and repository contracts. Selected public pages may open in a trusted Custom Tab, but the application itself is not a WebView shell.
Milestone lifecycle
From question to verified checkpoint
Each milestone is sized before work begins and closes only after implementation, proportionate validation, evidence, documentation, and focused Git history are complete.
- 1
Establish current behavior
Read the smallest relevant source and evidence set. Reproduce the behavior before editing, and preserve unrelated user work.
- 2
Research the contract
Verify station responses, Android behavior, policy boundaries, and capability differences. Unknowns remain explicit.
- 3
Define the vertical slice
Model immutable state and repository contracts, then identify UI actions, data adapters, playback boundaries, and failure states.
- 4
Implement through the layers
Compose renders state, ViewModels coordinate, repository implementations own protocols, and Media3 remains service-owned.
- 5
Validate narrowly first
Target affected unit tests and Kotlin compilation before broader lint, bundle, emulator, or physical-device checks.
- 6
Record evidence
Update milestone documents and the chronological README roadmap with verified results, limitations, and remaining device or owner checks.
- 7
Publish and observe
Create a focused commit and PR, let GitHub Actions validate it, post the change summary to Discord, and verify the merged result.
Repository map
Where responsibilities live
app/src/main/.../uiCompose and ViewModels
Adaptive screens, immutable UI state, actions, navigation shell, dialogs, and Material theme.
app/src/main/.../domainModels and contracts
Station identities, capabilities, repository interfaces, playback boundary, and trust policies.
app/src/main/.../dataStation implementations
Remote adapters, defensive parsers, encrypted session persistence, polling limits, and local preferences.
app/src/main/.../playbackMedia service
ExoPlayer, MediaSession, MediaController adapter, notification behavior, stream fallback, and recovery.
app/src/testLocal behavior tests
Domain rules, parsers, repositories, ViewModels, state transitions, and release helpers.
app/src/androidTestConnected UI tests
Compose semantics, adaptive layouts, navigation, accessibility, screenshots, and device-state behavior.
docsResearch and evidence
Protocol research, validation records, station certifications, device matrices, Play readiness, and release notes.
.github/workflowsContinuous validation
Android build/test/lint assembly, Pages generation/deployment, and Discord result notification.
Current candidate toolchain
Modern Android, narrow dependencies
LanguageKotlin 2.2.21
UIJetpack Compose
PlaybackMedia3 1.10.1
ImagesCoil 3.4.0
AndroidAPI 26–36
Packaging16 KB ready
The project remains a single Android application module. It will split only when stable boundaries justify the added Gradle complexity.
Contribute responsibly
Focused changes, clear evidence.
Open an issue before a large feature or protocol change, branch from main, preserve layer boundaries, add tests, and never publish protected station or signing data.