ashwkun/box.lore.android

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.