Skip to content

Architecture

Jump to bottom
Aswin C edited this page Mar 27, 2026 · 1 revision

Architecture

BoxCast is structured to separate the fast, edge-cached discovery backend from the native, highly modular Android application.

📱 Android App (Multi-Module)

The Android Client is a multi-module Gradle project following Google's modern Android architecture recommendations (Feature-First):

Core Modules

  • core/network: Retrofit API client, kotlinx.serialization network models.
  • core/data: Repositories, Room database DAOs, background download services, and the Media3 playback service.
  • core/model: Shared domain models (Podcast, Episode).
  • core/designsystem: The source of truth for the Material 3 Expressive theme, typography, shapes, spring motion, and reusable UI components.

Feature Modules

  • feature/home: Hero carousel, curated time-block sections, smart shuffle.
  • feature/player: Full interactive player, queue management, speed/sleep controls.
  • feature/explore: Genre browsing, charts, semantic discovery.
  • feature/library: Subscriptions, parallel downloads, liked lists, history.
  • feature/info: Podcast and episode detail screens.

Stack: Jetpack Compose, Coil, Retrofit, Room, Media3 / ExoPlayer.

🌐 Hybrid Backend Proxy

Instead of connecting the Android app directly to a slow, monolithic API, BoxCast connects to a custom Cloudflare Worker (TypeScript) proxy sitting at the edge, backed by a Turso (distributed SQLite) database.

The Hybrid Strategy:

  1. Edge Database for Speed (/trending): Top charts, curated metadata, and trending episodes are scraped daily and stored in Turso. When the app hits /trending, the Cloudflare Worker serves it directly from the local SQLite edge database, resulting in lightning-fast initial renders.
  2. Live Proxy for Freshness (/sync): When checking for new episodes from a user's local subscriptions, fetching from a database cache isn't good enough. The Worker proxies /sync requests directly to the Podcast Index API in parallel to guarantee 100% freshness.
  3. Hybrid Search (/search): Search queries hit the DB for instant popular matches and simultaneously hit the Podcast Index API for global long-tail coverage. The Android client then cross-references this with the local Room DB to badge subscribed podcasts.

Data Pipeline

A GitHub Actions workflow (sync-pi-data.yml) runs on a cron schedule to scrape Apple Podcast charts, ingest the mammoth Podcast Index local data dumps, and update the Turso database to keep the edge cache perfectly primed for the workers.

Clone this wiki locally