Home

boxlore wiki

boxlore is a podcast app for Android that finds shows by idea, not just by name, then stays quiet while you listen. This wiki explains how the Android app is built: its modules, how it stores your library, how recommendations work, and the catalog jobs that live in this repository.

To install boxlore or see what's new, start with the README.

---

What boxlore is built around

• Curious. It finds podcasts by idea. Search for a topic, follow a question in Lore, play the boxlore brief, or let recommendations suggest what's next.
• Calm. There are no app ads, and no feature sits behind a paywall. Podcasts may still carry ads from their creators. Show and episode pages can take their colours from the artwork, and the app stays out of the way while you listen.
• Yours. Whatever you want it to be: themes, custom colours, Pure, floating or classic navigation, lettering, seek amounts, intro and outro skipping, your own tags and icons, folders, any RSS feed, OPML and full backup.

---

How recommendations work

Recommendations are boxlore's main differentiator, and they are hybrid:

1. On the server: the app sends a bounded set of listening seeds, such as recent episodes you liked, finished or played. boxlore's private API uses semantic matching against the podcast catalog to return candidate shows and episodes.
2. On the phone: :core:ranking re-ranks those candidates for your habits with a LinUCB-style contextual bandit and taste meters that decay over time. That state is stored on the phone in adaptive_ranking_database.

Retrieval always happens on the server first; the phone only reorders what comes back. Recommendation & Ranking covers both stages, and What we track and why explains what leaves the phone.

---

Architecture in brief

1. Your library lives on the phone. The shows you follow, history, folders, the queue and downloads live in Room databases and DataStore on the device. An optional account adds cloud backup and library sync.
2. Hybrid recommendations. Server retrieval, then on-device re-ranking, as above.
3. Material 3 with solid surfaces. Cards and panels use solid Material 3 surfaces. Show and episode pages can follow the artwork's colours.
4. Podcasting 2.0. Chapters, with a fallback to timestamps in show notes; SRT and VTT transcripts; and funding links.
5. Playback in a Media3 service. One playback service owns the queue and Smart Queue refill, and serves Android Auto and Google Cast.

---

Technical stack

Layer	Technologies
Language and platform	Kotlin 2.x, JDK 17, Android min SDK 31, target and compile SDK 36
UI	Jetpack Compose, Material 3, Navigation Compose, Coil 2 for images
Audio and media	AndroidX Media3 (ExoPlayer, MediaSession, MediaLibraryService for Android Auto), Google Cast
Persistence	Room, Jetpack DataStore (Preferences), SharedPreferences (legacy files migrated by PrefsFileMigrator)
Networking and feeds	OkHttp 4, Retrofit 2, kotlinx.serialization, RSS Parser plus a custom XmlPullParser feed client
On-device ranking	LinUCB-style contextual bandit and Bayesian taste meters in :core:ranking
Private services	boxlore API for semantic search, candidate retrieval and the catalog. Not in this repository.
Quality	JUnit 5 (with the Vintage engine for older JUnit 4 tests), kotlinx-coroutines-test, Turbine, Robolectric, Konsist, Detekt, ktlint, Kover

---

System overview

flowchart TB
    subgraph UI_Layer ["Features (Jetpack Compose)"]
        Home[":feature:home"]
        Explore[":feature:explore"]
        Player[":feature:player"]
        Library[":feature:library"]
        Info[":feature:info"]
        Settings[":feature:settings"]
        History[":feature:history"]
        Onboarding[":feature:onboarding"]
        Briefing[":feature:briefing"]
        Widgets[":feature:widgets"]
    end

    subgraph App_Shell [":app (composition root)"]
        AppContainer["AppContainer"]
        BoxLoreApp["BoxLoreApplication"]
    end

    subgraph Core_Services ["Playback and catalog"]
        Playback[":core:playback (Media3 service, queue)"]
        Downloads[":core:downloads (downloads, workers)"]
        Catalog[":core:catalog (shows, folders, backup)"]
        Ranking[":core:ranking (on-device re-ranking)"]
    end

    subgraph Core_Data ["Data and infrastructure"]
        Database[":core:database (Room: boxlore_database)"]
        AdaptiveDB["Room: adaptive_ranking_database"]
        Prefs[":core:prefs (DataStore: user_preferences)"]
        Network[":core:network (boxlore API client)"]
        Auth[":core:auth (optional account)"]
        RSS[":core:rss (RSS feeds)"]
        Design[":core:designsystem (theme, components)"]
        Analytics[":core:analytics (façade)"]
    end

    API["boxlore API (private)"]

    AppContainer --> UI_Layer
    UI_Layer --> Playback
    UI_Layer --> Catalog
    UI_Layer --> Downloads
    UI_Layer --> Design
    UI_Layer --> Analytics
    UI_Layer --> Ranking

    Playback --> Catalog
    Playback --> Downloads
    Playback --> Ranking
    Catalog --> Database
    Catalog --> Network
    Catalog --> RSS
    Catalog --> Prefs
    Catalog --> Ranking
    Ranking --> AdaptiveDB
    Network --> Auth
    Network -.->|HTTPS| API

Loading

---

Pages

• Features What boxlore does: recommendations, search by idea, Lore and the boxlore brief; playback; Podcasting 2.0; folders, tags and icons; Smart Queue and downloads; appearance; Android Auto, Cast and widgets; backup and sync.
• System Architecture Modules, dependency direction, the AppContainer composition root, playback, and the identity contracts that keep upgrades working.
• Data & Storage Contracts boxlore_database (Room v38), adaptive_ranking_database, DataStore, SharedPreferences files, ID schemes and the backup format (version 6).
• Recommendation & Ranking Server retrieval, on-device re-ranking, taste meters, rewards, diversity and cold start.
• Catalog Sync & Ingestion The staged catalog pipeline (01–07), vectors for search, Turso paging rules, and new-episode alerts.

---

About the code

The Android app's code is source-available under the PolyForm Strict License 1.0.0. It isn't open source. The servers behind search, recommendations and the catalog are private.