Home

boxlore Documentation

Welcome to the official technical documentation and architecture wiki for boxlore, an advanced, local-first podcast client engineered for the Android platform.

boxlore combines modern Android engineering patterns—including Jetpack Compose, AndroidX Media3 (ExoPlayer), Room Database, and Kotlin Coroutines/Flow—with an on-device contextual recommendation engine, comprehensive Podcasting 2.0 support, and resilient offline synchronization.

---

Architectural Principles

1. Local-First Architecture
   Subscriptions, listening history, custom folders, queue states, and downloaded media reside directly in on-device SQLite databases and data stores, ensuring high responsiveness and offline reliability.
2. On-Device Contextual Personalization
   Recommendations are computed locally using an on-device LinUCB (Linear Upper Confidence Bound) bandit algorithm paired with exponential-decay taste meters, adapting discovery dynamically directly on the device.
3. Strict Material 3 Design System
   Constructed with solid Material 3 surfaces (avoiding unstable translucent or glassmorphic elements), dynamic palette extraction for album art luminescence, physics-based springs, and adaptive layouts optimized for mobile displays.
4. Podcasting 2.0 Standards Compliance
   Native handling of interactive chapters (with automated fallback to show note timestamps), synchronized word-level transcripts, soundbites, and creator funding metadata.
5. Robust Audio/Video Playback Lifecycle
   Decoupled playback service utilizing AndroidX Media3, background queue continuation, smart auto-downloads, Android Auto integration with reconnect state recovery, and Google Cast streaming.

---

Technical Stack

Layer	Technologies
Language & Platform	Kotlin 2.x, Android SDK (Min SDK 26, Target SDK 35, Build Tools 36), Java 17
UI Framework	Jetpack Compose, Material 3, Navigation Component, Coil 3 (Image Loading)
Audio & Media	AndroidX Media3 1.5+, ExoPlayer, MediaSession, Cast Extension, Android Auto MediaLibrarySession
Persistence	SQLite / Room 2.6+, Jetpack DataStore Preferences, SharedPreferences (Migrated via PrefsFileMigrator)
Networking & Feeds	OkHttp 4.x, Retrofit 2.x, Kotlinx Serialization, XmlPullParser (Custom RSS Engine)
Machine Learning	On-Device Contextual Multi-Armed Bandit (LinUCB) over SQLite, Client-Side Taste Scoring
External Services	Qdrant (Vector Embeddings for Concept Discovery), Turso Edge Database (Stateless Candidate Feeds)
Quality & Verification	JUnit 5, Kotlinx Coroutines Test, Turbine, Konsist (Architecture-as-code), Detekt, Ktlint, Kover

---

System Overview

flowchart TB
    subgraph UI_Layer ["Presentation Layer (Jetpack Compose)"]
        Home[":feature:home"]
        Explore[":feature:explore"]
        Player[":feature:player"]
        Library[":feature:library"]
        Info[":feature:info"]
        Briefing[":feature:briefing"]
        Widgets[":feature:widgets"]
    end

    subgraph App_Shell [":app (Composition Root)"]
        AppContainer["AppContainer (Single DI Root)"]
        BoxLoreApp["BoxLoreApplication"]
    end

    subgraph Core_Services ["Domain & Playback Core"]
        Playback[":core:playback (Media3 Service & Queue)"]
        Downloads[":core:downloads (Smart Downloads Worker)"]
        Catalog[":core:catalog (Podcast & Folder Repository)"]
        Ranking[":core:ranking (On-Device LinUCB Engine)"]
    end

    subgraph Core_Data ["Data & Infrastructure Core"]
        Database[":core:database (Room: boxlore_database)"]
        AdaptiveDB[":core:ranking (Room: adaptive_ranking_database)"]
        Prefs[":core:prefs (DataStore user_preferences)"]
        Network[":core:network (Retrofit / OkHttp)"]
        RSS[":core:rss (Custom XML Engine)"]
        Design[":core:designsystem (Theme & Solid Components)"]
        Analytics[":core:analytics (Facade)"]
    end

    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
    AppContainer --> UI_Layer

Loading

---

Wiki Contents

Detailed technical specifications and operational manuals are organized across the following chapters:

• System Architecture
  Module graph structure, dependency hierarchy, single composition root (AppContainer), presentation patterns, and strict architectural isolation rules enforced by Konsist.
• Features & Capabilities
  Comprehensive feature breakdown covering Subscription Folders (1×1 to 3×3 adaptive layouts), Custom Podcast Tags & Icons, Podcasting 2.0 (Chapters & Transcripts), Media3 Playback Engine, Smart Queue, Smart Downloads, Discovery Deck, and Backup & Restore.
• Data & Storage Contracts
  Formal schemas and migration strategies for boxlore_database (Room v36), adaptive_ranking_database, DataStore user_preferences, SharedPreferences bridges, and Version 6 JSON Backup specification.
• Recommendation & Ranking
  Deep dive into the local-first personalization model: LinUCB contextual bandits, feature vector formulation, exponential taste decay meters, exposure tracking, and cold-start fallback strategies.
• Catalog Sync & Ingestion
  Overview of the catalog sync pipeline running on dedicated VPS infrastructure: staged data processing (01–07), Qdrant vector space integration, Turso paging strategies, and Firebase RTDB new-episode notifications.