Skip to main content
BBPlayer is a local-first Bilibili audio player built with React Native, designed to provide a lightweight and smooth music listening experience. The application follows a monorepo architecture with clear separation between mobile app, backend services, and shared packages.

​
System Architecture

BBPlayer uses a local-first architecture where the mobile app operates independently with local data storage, while an optional backend service provides cloud synchronization and server-side features. 
┌─────────────────────────────────────────────────────────────┐
│                      BBPlayer Ecosystem                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐           ┌──────────────┐              │
│  │              │           │              │              │
│  │   Mobile     │◄─────────►│   Backend    │              │
│  │     App      │  Optional │   Service    │              │
│  │  (React      │  Sync     │  (Hono +     │              │
│  │   Native)    │           │  Cloudflare) │              │
│  │              │           │              │              │
│  └──────┬───────┘           └──────────────┘              │
│         │                                                  │
│         │                                                  │
│         ▼                                                  │
│  ┌──────────────┐                                         │
│  │   Shared     │                                         │
│  │  Packages    │                                         │
│  │              │                                         │
│  └──────────────┘                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

​
Core Components

​
Mobile Application

The mobile app (apps/mobile) is the primary user-facing component built with:
  • React Native 0.83.1 with React 19.2.0
  • Expo 55 (preview) for development and build tooling
  • Expo Router for file-based navigation
  • Local SQLite database using Drizzle ORM for data persistence

State Management

Zustand for lightweight, performant state management across the app

Data Fetching

React Query (TanStack Query) for server state management and caching

UI Framework

React Native Paper implementing Material Design 3 with Monet theming

Audio Playback

@bbplayer/orpheus custom audio module based on Android Media3

​
Backend Service

The backend (apps/backend) is a serverless API built with:
  • Hono web framework
  • Cloudflare Workers for deployment
  • PostgreSQL with Drizzle ORM
  • ArkType for runtime validation
The backend service is optional. The mobile app is designed to work fully offline with local data storage.

​
Shared Packages

The monorepo includes several shared packages that encapsulate reusable functionality:

@bbplayer/orpheus

Audio playback module built on Expo modules and Android Media3 ExoPlayer

@bbplayer/splash

Lyrics parsing and conversion library supporting SPL format with word-level timing

@bbplayer/image-theme-colors

Extract theme colors from images using Expo ImageRef for Material You theming

@bbplayer/logs

Performance-aware logger with namespaces and custom transports

​
Data Flow

​
Local-First Data Model

BBPlayer prioritizes local data storage and offline functionality:
  1. Local SQLite Database: Stores playlists, downloads, play history, and metadata
  2. MMKV Storage: Fast key-value storage for app settings and cache
  3. File System: Audio files, lyrics, and exported media

​
Feature Architecture

The mobile app organizes features by domain:
  • Player: Audio playback, queue management, lyrics display, danmaku
  • Library: Playlists, collections, favorites from Bilibili account
  • Downloads: Offline caching and export to M4A with metadata
  • Home: Search, quick access, recommendations
  • Leaderboard: Play history statistics and rankings
Each feature is self-contained with its own components, hooks, and business logic, following a feature-sliced architecture pattern.

​
Technology Philosophy

​
Performance-First

  • React Compiler: Uses React 19’s compiler for automatic optimization
  • Native Modules: Custom Expo modules for performance-critical operations
  • Efficient List Rendering: Shopify FlashList for smooth scrolling
  • Reanimated 4.2: Smooth animations running on UI thread

​
Developer Experience

  • TypeScript 5.9: Full type safety across the monorepo
  • Monorepo with pnpm: Efficient package management with workspaces
  • Modern Tooling: Oxlint, Oxfmt for fast linting and formatting
  • Git Hooks: Lefthook for automated quality checks

​
Platform Integration

  • Material Design 3: Native Android design language
  • Edge-to-Edge: Full-screen immersive experience
  • Monet Theming: Dynamic color extraction from album art
  • Native Gestures: React Native Gesture Handler for smooth interactions

​
Next Steps

Monorepo Structure

Learn about the workspace organization and package relationships

Tech Stack Details

Deep dive into the technologies powering BBPlayer

Build docs developers (and LLMs) love

Get started for freeTalk to us