# listenupapp/listenup architecture

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

- Interactive diagram: https://gitdiagram.com/listenupapp/listenup
- Repository: https://github.com/listenupapp/listenup

## Overview

ListenUp is a self-hosted audiobook platform: users connect Android, iOS, or browser clients to their own server to browse a library, play or download books, and keep listening progress synchronized across devices. The server also hosts the web client and transcodes formats browsers cannot play. The graph reflects README-documented workflows and sampled sync, playback, authentication, and transcode internals; several feature areas are represented at their exact enclosing directories because their implementation files were not sampled.

Main entry points: [`app/sharedUI/src`](https://github.com/listenupapp/listenup/tree/main/app/sharedUI/src) (Native apps), [`app/iosApp/ListenUp`](https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp) (iOS app), [`server/src/commonMain/kotlin/com/calypsan/listenup/server`](https://github.com/listenupapp/listenup/tree/main/server/src/commonMain/kotlin/com/calypsan/listenup/server) (ListenUp server), [`app/webApp/src/jsMain/kotlin/com/calypsan/listenup/web`](https://github.com/listenupapp/listenup/tree/main/app/webApp/src/jsMain/kotlin/com/calypsan/listenup/web) (Web client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client apps"]
  node_native["Native apps"]
  node_ios["iOS app"]
  node_web["Web client"]
  node_player["Audio playback<br/>[AudioEngine.swift]"]
  node_androidplay["Android playback service<br/>[PlaybackService.kt]"]
end

subgraph group_shared["Shared client core"]
  node_sync["Sync engine"]
  node_localdb[("Offline library store")]
  node_downloads["Book downloads"]
end

subgraph group_server["Server platform"]
  node_server["ListenUp server"]
  node_sessions["Session service<br/>[SessionService.kt]"]
  node_changebus["Change event bus<br/>[ChangeBus.kt]"]
  node_transcode["Media transcoding"]
end

subgraph group_contract["Shared contract"]
  node_auth["Authentication contract<br/>[AuthService.kt]"]
  node_secure["Secure credentials<br/>[SecureStorage.kt]"]
  node_syncframe["Sync messages<br/>[SyncFrame.kt]"]
end

subgraph group_features["Library features"]
  node_catalog[("Library catalog")]
  node_discovery["Catalog discovery"]
  node_reader["Document reader"]
  node_admin["Library administration"]
  node_social["Social listening"]
end

node_listener(("Listener"))
node_external(("User server"))

node_listener -->|"uses"| node_native
node_listener -->|"uses"| node_ios
node_listener -->|"uses"| node_web
node_native -->|"connects to"| node_server
node_ios -->|"connects to"| node_server
node_web -->|"served by"| node_server
node_native -->|"plays audio"| node_player
node_ios -->|"plays audio"| node_player
node_androidplay -.->|"plays audio"| node_player
node_native -->|"downloads books"| node_downloads
node_ios -->|"downloads books"| node_downloads
node_downloads -->|"stores offline"| node_localdb
node_sync -.->|"uses local state"| node_localdb
node_sync -.->|"exchanges frames"| node_syncframe
node_sync -->|"syncs progress"| node_server
node_changebus -->|"delivers live changes"| node_sync
node_native -->|"authenticates via"| node_auth
node_ios -->|"authenticates via"| node_auth
node_sessions -.->|"implements sessions"| node_auth
node_auth -.->|"stores credentials"| node_secure
node_server -->|"serves library"| node_catalog
node_native -->|"browses catalog"| node_discovery
node_ios -->|"browses catalog"| node_discovery
node_web -->|"browses catalog"| node_discovery
node_web -->|"requests playable media"| node_transcode
node_server -->|"transcodes formats"| node_transcode
node_native -->|"reads supplements"| node_reader
node_ios -->|"reads supplements"| node_reader
node_native -->|"manages library"| node_admin
node_ios -->|"manages library"| node_admin
node_native -->|"views activity"| node_social
node_ios -->|"views activity"| node_social
node_external -->|"hosts"| node_server

click node_native "https://github.com/listenupapp/listenup/tree/main/app/sharedUI/src"
click node_ios "https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp"
click node_web "https://github.com/listenupapp/listenup/tree/main/app/webApp/src/jsMain/kotlin/com/calypsan/listenup/web"
click node_player "https://github.com/listenupapp/listenup/blob/main/app/iosApp/ListenUp/Features/Player/AudioEngine.swift"
click node_androidplay "https://github.com/listenupapp/listenup/blob/main/app/sharedUI/src/androidMain/kotlin/com/calypsan/listenup/client/playback/PlaybackService.kt"
click node_sync "https://github.com/listenupapp/listenup/tree/main/app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/sync"
click node_localdb "https://github.com/listenupapp/listenup/tree/main/app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/local/db"
click node_downloads "https://github.com/listenupapp/listenup/tree/main/app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/download"
click node_auth "https://github.com/listenupapp/listenup/blob/main/contract/src/commonMain/kotlin/com/calypsan/listenup/api/AuthService.kt"
click node_secure "https://github.com/listenupapp/listenup/blob/main/contract/src/commonMain/kotlin/com/calypsan/listenup/core/SecureStorage.kt"
click node_syncframe "https://github.com/listenupapp/listenup/blob/main/contract/src/commonMain/kotlin/com/calypsan/listenup/api/sync/SyncFrame.kt"
click node_server "https://github.com/listenupapp/listenup/tree/main/server/src/commonMain/kotlin/com/calypsan/listenup/server"
click node_sessions "https://github.com/listenupapp/listenup/blob/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/auth/SessionService.kt"
click node_changebus "https://github.com/listenupapp/listenup/blob/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/sync/ChangeBus.kt"
click node_transcode "https://github.com/listenupapp/listenup/blob/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/transcode/TranscodeSessionEngine.kt"
click node_catalog "https://github.com/listenupapp/listenup/tree/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/services"
click node_discovery "https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/Discover"
click node_reader "https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/DocumentReader"
click node_admin "https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/Admin"
click node_social "https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/Discover"

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_native,node_ios,node_web,node_player,node_androidplay,node_external toneBlue
class node_sync,node_localdb,node_downloads toneAmber
class node_server,node_sessions,node_changebus,node_transcode toneMint
class node_auth,node_secure,node_syncframe toneRose
class node_catalog,node_discovery,node_reader,node_admin,node_social,node_listener toneIndigo
```

## Components

### Client apps

- [Native apps](https://github.com/listenupapp/listenup/tree/main/app/sharedUI/src): `app/sharedUI/src`
- [iOS app](https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp): `app/iosApp/ListenUp`
- [Web client](https://github.com/listenupapp/listenup/tree/main/app/webApp/src/jsMain/kotlin/com/calypsan/listenup/web): `app/webApp/src/jsMain/kotlin/com/calypsan/listenup/web`
- [Audio playback](https://github.com/listenupapp/listenup/blob/main/app/iosApp/ListenUp/Features/Player/AudioEngine.swift): `app/iosApp/ListenUp/Features/Player/AudioEngine.swift`
- [Android playback service](https://github.com/listenupapp/listenup/blob/main/app/sharedUI/src/androidMain/kotlin/com/calypsan/listenup/client/playback/PlaybackService.kt): `app/sharedUI/src/androidMain/kotlin/com/calypsan/listenup/client/playback/PlaybackService.kt`

### Shared client core

- [Sync engine](https://github.com/listenupapp/listenup/tree/main/app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/sync): `app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/sync`
- [Offline library store](https://github.com/listenupapp/listenup/tree/main/app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/local/db): `app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/local/db`
- [Book downloads](https://github.com/listenupapp/listenup/tree/main/app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/download): `app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/download`

### Server platform

- [ListenUp server](https://github.com/listenupapp/listenup/tree/main/server/src/commonMain/kotlin/com/calypsan/listenup/server): `server/src/commonMain/kotlin/com/calypsan/listenup/server`
- [Session service](https://github.com/listenupapp/listenup/blob/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/auth/SessionService.kt): `server/src/commonMain/kotlin/com/calypsan/listenup/server/auth/SessionService.kt`
- [Change event bus](https://github.com/listenupapp/listenup/blob/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/sync/ChangeBus.kt): `server/src/commonMain/kotlin/com/calypsan/listenup/server/sync/ChangeBus.kt`
- [Media transcoding](https://github.com/listenupapp/listenup/blob/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/transcode/TranscodeSessionEngine.kt): `server/src/commonMain/kotlin/com/calypsan/listenup/server/transcode/TranscodeSessionEngine.kt`

### Shared contract

- [Authentication contract](https://github.com/listenupapp/listenup/blob/main/contract/src/commonMain/kotlin/com/calypsan/listenup/api/AuthService.kt): `contract/src/commonMain/kotlin/com/calypsan/listenup/api/AuthService.kt`
- [Secure credentials](https://github.com/listenupapp/listenup/blob/main/contract/src/commonMain/kotlin/com/calypsan/listenup/core/SecureStorage.kt): `contract/src/commonMain/kotlin/com/calypsan/listenup/core/SecureStorage.kt`
- [Sync messages](https://github.com/listenupapp/listenup/blob/main/contract/src/commonMain/kotlin/com/calypsan/listenup/api/sync/SyncFrame.kt): `contract/src/commonMain/kotlin/com/calypsan/listenup/api/sync/SyncFrame.kt`

### Library features

- [Library catalog](https://github.com/listenupapp/listenup/tree/main/server/src/commonMain/kotlin/com/calypsan/listenup/server/services): `server/src/commonMain/kotlin/com/calypsan/listenup/server/services`
- [Catalog discovery](https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/Discover): `app/iosApp/ListenUp/Features/Discover`
- [Document reader](https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/DocumentReader): `app/iosApp/ListenUp/Features/DocumentReader`
- [Library administration](https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/Admin): `app/iosApp/ListenUp/Features/Admin`
- [Social listening](https://github.com/listenupapp/listenup/tree/main/app/iosApp/ListenUp/Features/Discover): `app/iosApp/ListenUp/Features/Discover`

### Other components

- **Listener**
- **User server**

## Connections

- Listener → Native apps: uses
- Listener → iOS app: uses
- Listener → Web client: uses
- Native apps → ListenUp server: connects to
- iOS app → ListenUp server: connects to
- Web client → ListenUp server: served by
- Native apps → Audio playback: plays audio
- iOS app → Audio playback: plays audio (evidence: `app/iosApp/ListenUp/Features/Player/AudioEngine.swift`)
- Android playback service → Audio playback: plays audio
- Native apps → Book downloads: downloads books
- iOS app → Book downloads: downloads books
- Book downloads → Offline library store: stores offline (evidence: `app/sharedLogic/src/appleMain/kotlin/com/calypsan/listenup/client/download/AppleDownloadService.kt`)
- Sync engine → Offline library store: uses local state (evidence: `app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/sync/PendingOperationQueue.kt`)
- Sync engine → Sync messages: exchanges frames (evidence: `app/sharedLogic/src/commonMain/kotlin/com/calypsan/listenup/client/data/sync/SyncEventDispatcher.kt`)
- Sync engine → ListenUp server: syncs progress
- Change event bus → Sync engine: delivers live changes
- Native apps → Authentication contract: authenticates via
- iOS app → Authentication contract: authenticates via
- Session service → Authentication contract: implements sessions
- Authentication contract → Secure credentials: stores credentials
- ListenUp server → Library catalog: serves library (evidence: `server/src/commonMain/kotlin/com/calypsan/listenup/server/services/CoverSearchService.kt`)
- Native apps → Catalog discovery: browses catalog
- iOS app → Catalog discovery: browses catalog
- Web client → Catalog discovery: browses catalog
- Web client → Media transcoding: requests playable media
- ListenUp server → Media transcoding: transcodes formats (evidence: `server/src/commonMain/kotlin/com/calypsan/listenup/server/transcode/TranscodeSessionEngine.kt`)
- Native apps → Document reader: reads supplements
- iOS app → Document reader: reads supplements
- Native apps → Library administration: manages library
- iOS app → Library administration: manages library
- Native apps → Social listening: views activity
- iOS app → Social listening: views activity
- User server → ListenUp server: hosts
