# ashwkun/box.lore.android architecture

> Architecture diagram of the GitHub repository ashwkun/box.lore.android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashwkun/box.lore.android
- Repository: https://github.com/ashwkun/box.lore.android

## Overview

1. **Repository shape**
   This is a modular Android app with a clear split between the UI shell, feature modules, and shared core modules. The app code lives in `app`, while reusable logic is divided into `core/model`, `core/network`, `core/data`, and `core/designsystem`. Feature-specific Compose UIs live under `feature/*`.

2. **App entry and presentation boundary**
   `BoxLoreApplication` and `MainActivity` are the Android entry points. From there, the app routes into feature screens such as home, explore, player, library, onboarding, briefing, and info. The UI layer is entirely Compose-based and relies on ViewModels for state rather than direct data access.

3. **Shared design system**
   `core/designsystem` is the visual and interaction layer used across all features. It contains the app theme, expressive Material 3 components, player controls, loaders, image optimization, share sheets, consent dialogs, and navigation bars. This module is the main boundary that keeps feature UIs visually consistent.

4. **Feature modules as bounded UI slices**
   Each feature module owns one part of the user journey:
   - `feature/home` for discovery, recommendations, hero content, and profile
   - `feature/explore` for search and browsing
   - `feature/player` for playback UI, queue, transcript, chapters, and mini/full player states
   - `feature/library` for downloads, history, likes, subscriptions, and smart-download settings
   - `feature/onboarding` for setup and AI/search/import flows
   - `feature/info` for podcast/episode detail and cross-promotion
   - `feature/briefing` for the daily briefing experience  
   These modules depend on core repositories and shared UI components, but not on each other directly.

5. **Domain and data orchestration**
   `core/data` is the application’s main business/data layer. It exposes repositories and managers for podcasts, episodes, playback, downloads, queueing, transcripts, user preferences, sharing, subscriptions, chapters, install referrers, and smart downloads. This is where app behavior is coordinated before reaching UI or infrastructure.

6. **Local persistence**
   The app uses a Room database in `core/data/database` to store podcasts, downloaded episodes, listening history, and queue items. DAOs and entities provide the persistent state for offline library features, resume positions, and queue restoration. This local store is the app’s source of truth for user-owned data.

7. **Media and background services**
   Playback and downloads are handled by dedicated Android services in `core/data/service`, including `BoxLorePlaybackService` and `MediaDownloadService`. The playback stack is centered on Media3/ExoPlayer and MediaSession, with the player UI controlling a long-lived service rather than playing audio directly in the screen layer. Smart download behavior is further managed by `SmartDownloadWorker`, `SmartDownloadManager`, and `SmartQueueEngine`.

8. **Network and external content sources**
   `core/network` defines the API layer (`BoxLoreApi`) and remote response models for Podcast Index, iTunes, radio, onboarding, transcripts, and sync data. The README indicates the app aggregates public podcast sources, especially Podcast Index and Apple Podcast Charts. Network responses are converted into shared models in `core/model`, which keeps API shape separate from app/domain shape.

9. **Recommendations, analytics, and personalization**
   The `core/data/analytics`, `crosspromo`, and `privacy` packages show that the app has an internal personalization layer beyond basic playback. Session aggregation, pending entry points, recommendation logic, cross-promotion detection/resolution, and consent management all sit in this core layer so features can consume curated content without embedding the logic in UI.

10. **Backup, sync, and offline resilience**
   `LibraryBackupManager`, `InstallReferrerManager`, `ThrottlingDataSource`, and the download/history repositories suggest the app is designed to survive app reinstalls and network variability. Offline content, listening history, and queue state are persisted locally, while backup/sync utilities help reconstruct or protect the library state.

11. **Operational data pipeline and backend maintenance**
   The repository also contains a non-Android operational layer: `scripts/` plus GitHub workflows for syncing podcast data, vectorizing content, restoring databases, backfilling metadata, and checking new episodes. This indicates a separate ingestion/maintenance pipeline that prepares remote catalog and ranking data for the app and any supporting backend storage.

12. **Distribution and web surface**
   `firebase.json`, `.firebaserc`, and the `web/` directory provide static hosting for privacy/share pages and app-links verification (`assetlinks.json`). The Android app also includes an `BoxLoreFcmService`, so push notifications are part of the supported runtime surface. These pieces are auxiliary to the app itself, but they matter for distribution, linking, and remote messaging.

Main entry points: [`core/data/src/main/java/cx/aswin/boxcast/core/data`](https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data) (Data Layer), [`core/network/src/main/java/cx/aswin/boxcast/core/network`](https://github.com/ashwkun/box.lore.android/tree/master/core/network/src/main/java/cx/aswin/boxcast/core/network) (Network API), [`core/designsystem/src/main/java/cx/aswin/boxcast/core/designsystem`](https://github.com/ashwkun/box.lore.android/tree/master/core/designsystem/src/main/java/cx/aswin/boxcast/core/designsystem) (Design System), [`app/src/main/java/cx/aswin/boxcast/MainActivity.kt`](https://github.com/ashwkun/box.lore.android/blob/master/app/src/main/java/cx/aswin/boxcast/MainActivity.kt) (Main Activity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App shell"]
  node_app_application["Application<br/>android entry"]
  node_app_activity["Main Activity<br/>android entry<br/>[MainActivity.kt]"]
  node_app_fcm["FCM Service<br/>push service"]
end

subgraph group_core_stack["Core stack"]
  node_core_design["Design System<br/>compose ui kit"]
  node_core_model["Models<br/>domain model"]
  node_core_network["Network API<br/>remote data"]
  node_core_data["Data Layer<br/>repositories"]
  node_core_db[("Room DB<br/>local store")]
  node_core_service["Media Services<br/>android service"]
  node_core_personalization["Personalization<br/>analytics & recs"]
end

subgraph group_feature_ui["Feature UI"]
  node_feature_home["Home<br/>feature module"]
  node_feature_explore["Explore<br/>feature module"]
  node_feature_player["Player<br/>feature module"]
  node_feature_library["Library<br/>feature module"]
  node_feature_onboarding["Onboarding<br/>feature module"]
  node_feature_info["Info<br/>feature module"]
  node_feature_briefing["Briefing<br/>feature module"]
end

subgraph group_ops_surface["Ops & web"]
  node_ops_pipeline["Pipelines<br/>scripts & ci"]
  node_web_surface["Web Surface<br/>static hosting"]
end

node_app_application -->|"wires"| node_core_data
node_app_activity -->|"enters"| node_feature_home
node_app_activity -->|"routes"| node_feature_onboarding
node_app_activity -->|"opens"| node_feature_player
node_app_fcm -->|"notifications"| node_core_personalization
node_feature_home -->|"reads"| node_core_data
node_feature_explore -->|"searches"| node_core_network
node_feature_player -->|"controls"| node_core_data
node_feature_library -->|"manages"| node_core_data
node_feature_onboarding -->|"collects"| node_core_network
node_feature_info -->|"details"| node_core_data
node_feature_briefing -->|"summarizes"| node_core_data
node_feature_home -->|"shares ui"| node_core_design
node_feature_player -->|"shares ui"| node_core_design
node_feature_library -->|"shares ui"| node_core_design
node_feature_info -->|"shares ui"| node_core_design
node_feature_onboarding -->|"shares ui"| node_core_design
node_core_data -->|"persists"| node_core_db
node_core_data -->|"dispatches"| node_core_service
node_core_data -->|"fetches"| node_core_network
node_core_network -->|"maps to"| node_core_model
node_core_data -->|"derives"| node_core_personalization
node_ops_pipeline -.->|"feeds"| node_core_network
node_ops_pipeline -.->|"restores"| node_core_db
node_web_surface -.->|"supports"| node_app_activity
node_web_surface -.->|"publishes"| node_ops_pipeline

click node_app_application "https://github.com/ashwkun/box.lore.android/blob/master/app/src/main/java/cx/aswin/boxcast/BoxLoreApplication.kt"
click node_app_activity "https://github.com/ashwkun/box.lore.android/blob/master/app/src/main/java/cx/aswin/boxcast/MainActivity.kt"
click node_app_fcm "https://github.com/ashwkun/box.lore.android/blob/master/app/src/main/java/cx/aswin/boxcast/fcm/BoxLoreFcmService.kt"
click node_core_design "https://github.com/ashwkun/box.lore.android/tree/master/core/designsystem/src/main/java/cx/aswin/boxcast/core/designsystem"
click node_core_model "https://github.com/ashwkun/box.lore.android/tree/master/core/model/src/main/java/cx/aswin/boxcast/core/model"
click node_core_network "https://github.com/ashwkun/box.lore.android/tree/master/core/network/src/main/java/cx/aswin/boxcast/core/network"
click node_core_data "https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data"
click node_core_db "https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data/database"
click node_core_service "https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data/service"
click node_core_personalization "https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data/analytics"
click node_feature_home "https://github.com/ashwkun/box.lore.android/tree/master/feature/home/src/main/java/cx/aswin/boxcast/feature/home"
click node_feature_explore "https://github.com/ashwkun/box.lore.android/tree/master/feature/explore/src/main/java/cx/aswin/boxcast/feature/explore"
click node_feature_player "https://github.com/ashwkun/box.lore.android/tree/master/feature/player/src/main/java/cx/aswin/boxcast/feature/player"
click node_feature_library "https://github.com/ashwkun/box.lore.android/tree/master/feature/library/src/main/java/cx/aswin/boxcast/feature/library"
click node_feature_onboarding "https://github.com/ashwkun/box.lore.android/tree/master/feature/onboarding/src/main/java/cx/aswin/boxcast/feature/onboarding"
click node_feature_info "https://github.com/ashwkun/box.lore.android/tree/master/feature/info/src/main/java/cx/aswin/boxcast/feature/info"
click node_feature_briefing "https://github.com/ashwkun/box.lore.android/tree/master/feature/briefing/src/main/java/cx/aswin/boxcast/feature/briefing"
click node_ops_pipeline "https://github.com/ashwkun/box.lore.android/tree/master/scripts"
click node_web_surface "https://github.com/ashwkun/box.lore.android/tree/master/web"

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_app_application,node_app_activity,node_app_fcm toneBlue
class node_core_design,node_core_model,node_core_network,node_core_data,node_core_db,node_core_service,node_core_personalization toneAmber
class node_feature_home,node_feature_explore,node_feature_player,node_feature_library,node_feature_onboarding,node_feature_info,node_feature_briefing toneMint
class node_ops_pipeline,node_web_surface toneRose
```

## Components

### App shell

Android entry points and runtime services.

- [Application](https://github.com/ashwkun/box.lore.android/blob/master/app/src/main/java/cx/aswin/boxcast/BoxLoreApplication.kt): android entry · Process-level application setup and dependency wiring. · `app/src/main/java/cx/aswin/boxcast/BoxLoreApplication.kt`
- [Main Activity](https://github.com/ashwkun/box.lore.android/blob/master/app/src/main/java/cx/aswin/boxcast/MainActivity.kt): android entry · Host activity that enters the Compose UI and navigation flow. · `app/src/main/java/cx/aswin/boxcast/MainActivity.kt`
- [FCM Service](https://github.com/ashwkun/box.lore.android/blob/master/app/src/main/java/cx/aswin/boxcast/fcm/BoxLoreFcmService.kt): push service · Receives remote notifications for the app. · `app/src/main/java/cx/aswin/boxcast/fcm/BoxLoreFcmService.kt`

### Core stack

Shared model, network, data, and design system modules.

- [Design System](https://github.com/ashwkun/box.lore.android/tree/master/core/designsystem/src/main/java/cx/aswin/boxcast/core/designsystem): compose ui kit · Shared theme, controls, dialogs, loaders, and navigation chrome. · `core/designsystem/src/main/java/cx/aswin/boxcast/core/designsystem`
- [Models](https://github.com/ashwkun/box.lore.android/tree/master/core/model/src/main/java/cx/aswin/boxcast/core/model): domain model · Shared app-level entities for podcasts, episodes, briefing, and promotion. · `core/model/src/main/java/cx/aswin/boxcast/core/model`
- [Network API](https://github.com/ashwkun/box.lore.android/tree/master/core/network/src/main/java/cx/aswin/boxcast/core/network): remote data · API client and remote response models for podcast and sync sources. · `core/network/src/main/java/cx/aswin/boxcast/core/network`
- [Data Layer](https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data): repositories · Repository, manager, and orchestration layer for app behavior. · `core/data/src/main/java/cx/aswin/boxcast/core/data`
- [Room DB](https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data/database): local store · Persistent storage for podcasts, downloads, history, and queue state. · `core/data/src/main/java/cx/aswin/boxcast/core/data/database`
- [Media Services](https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data/service): android service · Long-lived playback and download services backed by Media3 and background work. · `core/data/src/main/java/cx/aswin/boxcast/core/data/service`
- [Personalization](https://github.com/ashwkun/box.lore.android/tree/master/core/data/src/main/java/cx/aswin/boxcast/core/data/analytics): analytics & recs · Consent, session aggregation, recommendations, and cross-promotion logic. · `core/data/src/main/java/cx/aswin/boxcast/core/data/analytics`

### Feature UI

Compose feature slices for the main user journeys.

- [Home](https://github.com/ashwkun/box.lore.android/tree/master/feature/home/src/main/java/cx/aswin/boxcast/feature/home): feature module · Discovery, recommendations, hero content, and profile entry points. · `feature/home/src/main/java/cx/aswin/boxcast/feature/home`
- [Explore](https://github.com/ashwkun/box.lore.android/tree/master/feature/explore/src/main/java/cx/aswin/boxcast/feature/explore): feature module · Search and browse experience for catalog discovery. · `feature/explore/src/main/java/cx/aswin/boxcast/feature/explore`
- [Player](https://github.com/ashwkun/box.lore.android/tree/master/feature/player/src/main/java/cx/aswin/boxcast/feature/player): feature module · Playback UI, queue, transcript, chapters, and mini/full player states. · `feature/player/src/main/java/cx/aswin/boxcast/feature/player`
- [Library](https://github.com/ashwkun/box.lore.android/tree/master/feature/library/src/main/java/cx/aswin/boxcast/feature/library): feature module · Downloads, listening history, likes, subscriptions, and smart downloads settings. · `feature/library/src/main/java/cx/aswin/boxcast/feature/library`
- [Onboarding](https://github.com/ashwkun/box.lore.android/tree/master/feature/onboarding/src/main/java/cx/aswin/boxcast/feature/onboarding): feature module · Setup flows for genres, search, import, and AI-guided suggestions. · `feature/onboarding/src/main/java/cx/aswin/boxcast/feature/onboarding`
- [Info](https://github.com/ashwkun/box.lore.android/tree/master/feature/info/src/main/java/cx/aswin/boxcast/feature/info): feature module · Podcast and episode detail screens plus cross-promotion UI. · `feature/info/src/main/java/cx/aswin/boxcast/feature/info`
- [Briefing](https://github.com/ashwkun/box.lore.android/tree/master/feature/briefing/src/main/java/cx/aswin/boxcast/feature/briefing): feature module · Daily briefing experience and its view state. · `feature/briefing/src/main/java/cx/aswin/boxcast/feature/briefing`

### Ops & web

Maintenance scripts, CI workflows, and hosted web assets.

- [Pipelines](https://github.com/ashwkun/box.lore.android/tree/master/scripts): scripts & ci · Operational scripts and GitHub workflows for sync, vectorization, and backfills. · `scripts`
- [Web Surface](https://github.com/ashwkun/box.lore.android/tree/master/web): static hosting · Hosted privacy/share pages and app-links verification assets. · `web`

## Connections

- Application → Data Layer: wires · Application scope initializes shared repositories and app services.
- Main Activity → Home: enters · Main activity hands off into the Compose navigation shell.
- Main Activity → Onboarding: routes · First-run setup can launch onboarding flows.
- Main Activity → Player: opens · Activity hosts the player surface and transitions.
- FCM Service → Personalization: notifications · Push handling connects to app-side session and entry-point logic.
- Home → Data Layer: reads · Home uses repositories for curated content and user state.
- Explore → Network API: searches · Browse/search flows depend on remote catalog access.
- Player → Data Layer: controls · Playback UI coordinates queue, chapters, transcripts, and playback state.
- Library → Data Layer: manages · Library surfaces downloads, history, subscriptions, and settings from data layer.
- Onboarding → Network API: collects · Setup screens pull remote discovery and import suggestions.
- Info → Data Layer: details · Episode and podcast info resolves local/remote content via repositories.
- Briefing → Data Layer: summarizes · Briefing composes a daily package from curated data.
- Home → Design System: shares ui · Feature screens reuse common theme and components.
- Player → Design System: shares ui · Player UI relies on shared controls and visual primitives.
- Library → Design System: shares ui · Library screens use the same shared design language.
- Info → Design System: shares ui · Info screens use shared cards, sheets, and themes.
- Onboarding → Design System: shares ui · Onboarding uses the shared Compose design system.
- Data Layer → Room DB: persists · Repositories store offline state and user-owned library data.
- Data Layer → Media Services: dispatches · Data layer starts and coordinates playback and download services.
- Data Layer → Network API: fetches · Repositories call remote APIs and map responses.
- Network API → Models: maps to · Remote payloads are normalized into shared models.
- Data Layer → Personalization: derives · Recommendations, consent, and cross-promo logic are centralized here.
- Pipelines → Network API: feeds · Sync and vectorization workflows prepare remote content data.
- Pipelines → Room DB: restores · Backfill and restore jobs operate on catalog and local database state.
- Web Surface → Main Activity: supports · Static pages and app-links assets support distribution and linking.
- Web Surface → Pipelines: publishes · Operational outputs can be deployed through hosted web assets.