How lifeisastory/my_pilipala works
1. What this repo is
PiliPala is a Flutter-based third-party BiliBili client. The app is primarily built for Android and iOS, but the repository also contains Flutter targets for web, Linux, macOS, and Windows. The architecture is centered on a single Flutter codebase with native platform shells.
2. Top-level structure
The repo is split into a few major layers: lib/ for application code, assets/ for static resources, platform folders for native packaging, and release/tooling folders such as .github/ and fastlane/. This is a productized mobile app repo, not just a library or demo.
3. Presentation layer: page-based feature modules
lib/pages/ is the largest subsystem and contains the app’s feature screens. The code is organized by domain: home, video, search, live, bangumi, dynamics, user/member, messages, favorites, history, settings, login, webview, and more. Most features follow a consistent controller.dart / view.dart / index.dart module pattern, suggesting a structured state-managed UI architecture.
4. Domain boundaries
The page tree reflects clear user-facing boundaries:
- Content discovery: home, hot, rank, rcmd, bangumi, live
- Search: search, search_panel, search_result
- Playback: video, media, danmaku, live_room
- Social/account: login, member, follow, fan, blacklist, message, whisper
- Personal data: history, later, fav, subscription, mine
- Settings: theme, playback, gestures, navigation, privacy, logs
This makes the app easy to map into architecture diagrams by feature domain.
5. Data layer: HTTP/API boundary
lib/http/ is the networking boundary. It contains API wrappers for specific BiliBili domains such as video, live, search, login, user, dynamics, favorites, messages, bangumi, replies, and HTML-related endpoints. The UI does not appear to talk directly to remote services; instead, pages go through these API modules.
6. Model layer
lib/models/ contains strongly typed data structures for the different API responses and app concepts. The repository has model groups for video, live, user, member, search, message, bangumi, dynamics, login, and common enums/configs. There is also generated protobuf support for danmaku (dm.proto and generated Dart files), showing that some data flows use binary/protobuf encoding rather than just JSON.
7. Playback and streaming subsystem
Video and live playback are a dedicated subsystem:
- lib/plugin/pl_player/ implements a custom player UI and playback state model
- lib/pages/video/detail/ orchestrates video detail, related content, replies, and playback entry points
- lib/pages/live_room/ handles live-room playback and controls
Supporting utilities include subtitle handling, video URL helpers, danmaku utilities, and signing logic. This area likely acts as the main orchestration point for media playback, quality selection, and interaction overlays.
8. Reusable UI and interaction components
lib/common/ contains shared widgets, skeleton/loading states, app bars, toasts, cards, HTML rendering, empty/error views, and stats components. These are the app’s presentation primitives used across many pages. The presence of “skeleton” widgets and shared card components indicates a UI built around repeated list/detail layouts.
9. Custom plugins and interaction surfaces
The lib/plugin/ folder contains several important in-app subsystems:
- pl_gallery for image preview/hero transitions
- pl_player for media playback
- pl_popup for overlay UI
- pl_socket for socket-based features, likely live or realtime messaging
These are architectural seams where the app implements richer interactions than a standard Flutter screen.
10. Services and app-wide runtime concerns
lib/services/ covers app lifecycle and background/runtime features: audio handling, audio session, battery optimization control, shutdown timer, logging, and service location. This suggests the app supports background media behavior and global services that are shared across pages rather than owned by a single feature.
11. Utilities and cross-cutting concerns
lib/utils/ includes app-wide helpers for storage, cookies, URL handling, proxies, event bus, caching, download/save, login/session helpers, route navigation, danmaku/subtitle processing, and recommendation filtering. These utilities form the glue between UI modules, API modules, and persistent device state.
12. Persistence and local state
While there is no explicit database folder in the tree, local persistence is implied by utilities such as storage.dart, cookie.dart, cache_manage.dart, and global_data_cache.dart. This is where user preferences, session/auth state, playback settings, and cached app data would be managed.
13. Assets and product packaging
assets/ contains fonts, images, loading animations, and screenshots. fastlane/metadata/ contains app store listing text and screenshots for multiple locales, which indicates a release-oriented mobile product. change_log/ tracks versioned release notes.
14. Platform integration
The native folders (android/, ios/, macos/, linux/, windows/, web/) are standard Flutter host shells. On Android and iOS the project includes native manifests, launch screens, and platform-specific app scaffolding. The app is therefore a single Flutter UI codebase with platform packaging, not a server/client split.
15. Build and release flow
CI/CD is handled through .github/workflows/ with separate beta and release pipelines. Combined with fastlane, this repo is set up for automated mobile builds and store metadata publication. That matters for an architecture diagram because the delivery pipeline is part of the system boundary.
16. Overall runtime flow
The main runtime path is: user interaction in a page module → controller/state logic → HTTP/API module → typed model parsing → UI update, with media-specific paths branching into player/danmaku/subtitle/live socket subsystems. Cross-cutting services like storage, logging, and audio/background support are available throughout the app, while platform folders only host the Flutter runtime.
Main entry points: app_pages.dart App routes · http/index.dart HTTP API · main.dart Main app · detail/index.dart Video detail
Components 23
Flutter app
Single Flutter codebase and native shells
- Main app · App bootstrap, routing, and top-level composition
lib/main.dart - App routes · Central route map for page navigation
lib/router/app_pages.dart - Android shell · Native Android packaging and launch shell
android/app/src/main/AndroidManifest.xml - iOS shell · Native iOS packaging and launch shell
ios/Runner/AppDelegate.swift - Desktop/web shell · Linux, macOS, Windows, and web host shells
linux/main.cc
Feature pages
Page-based user-facing modules
- Home feed · Landing feed and primary content discovery surface
lib/pages/home/index.dart - Search flow · Search entry, panels, and results
lib/pages/search/index.dart - Video detail · Video detail orchestration, related content, and replies
lib/pages/video/detail/index.dart - Live room · Live-room viewing and controls
lib/pages/live_room/index.dart - Social hub · Login, member, follow/fan, message, and whisper flows
lib/pages/login/index.dart - Library pages · History, later, favorites, subscriptions, and profile area
lib/pages/history/index.dart - Settings · Playback, style, privacy, navigation, and log settings
lib/pages/setting/index.dart
Data layer
Remote API, models, and local persistence
- HTTP API · Domain-specific API wrappers for BiliBili endpoints
lib/http/index.dart - Domain models · Strongly typed response and app state models, including danmaku protobufs
lib/models/common/index.dart - Local state · Cookies, storage, cache, login/session, and other device state helpers
lib/utils/storage.dart
Shared runtime
Reusable widgets, plugins, services, and utilities
- Player core · Custom playback UI, controls, and playback state management
lib/plugin/pl_player/index.dart - Gallery UI · Image preview and hero/interactive gallery interactions
lib/plugin/pl_gallery/index.dart - Realtime socket · Socket-based live or messaging interactions
lib/plugin/pl_socket/index.dart - App services · Audio, battery, shutdown timer, logging, and service locator
lib/services/service_locator.dart - Shared UI · Reusable cards, skeletons, app bars, errors, empty states, and HTML rendering
lib/common/widgets/appbar.dart - App utils · URL, auth, event bus, recommendation, media, download, and route helpers
lib/utils/utils.dart
Delivery
Assets, release metadata, and CI workflows
- Assets · Fonts, images, loading animations, and screenshots
assets - Release flow · Fastlane metadata, changelogs, and GitHub workflows for build and release
.github/workflows/release_ci.yml
Connections 32
- Main app → App routes: uses · Bootstraps navigation and app structure
- Main app → Home feed: launches · Starts in the main feature shell
- App routes → Home feed: routes · Navigates into content discovery
- App routes → Search flow: routes · Navigates into search flows
- App routes → Video detail: routes · Navigates into playback detail pages
- App routes → Live room: routes · Navigates into live-room playback
- App routes → Social hub: routes · Navigates into account and social pages
- App routes → Library pages: routes · Navigates into personal library pages
- App routes → Settings: routes · Navigates into settings pages
- Home feed → HTTP API: fetches · Loads content through HTTP modules
- Search flow → HTTP API: fetches · Queries search endpoints
- Video detail → HTTP API: fetches · Loads video detail, related, replies, and play data
- Live room → HTTP API: fetches · Loads live-room and stream metadata
- Social hub → HTTP API: fetches · Loads login, user, follow, fan, and message data
- Library pages → HTTP API: fetches · Loads history, favorites, subscriptions, and member data
- HTTP API → Domain models: parses · Converts responses into typed domain objects
- HTTP API → Local state: auth/state · Uses local persistence for cookies, cache, and session data
- Video detail → Player core: plays · Hands media sessions off to the player subsystem
- Live room → Player core: plays · Uses shared playback controls and state
- Video detail → Shared UI: renders · Builds detail layouts from shared UI primitives
- Home feed → Shared UI: renders · Uses shared cards, skeletons, and empty states
- Search flow → Shared UI: renders · Uses shared search and result components
- Social hub → Realtime socket: realtime · Connects to live or message socket flows
- Video detail → App utils: helpers · Uses URL, danmaku, subtitle, and recommendation helpers
- App services → Player core: supports · Provides audio/background media runtime support
- App services → Local state: supports · Coordinates app-wide runtime state and persistence
- Shared UI → Assets: loads · Consumes app imagery, fonts, and loading assets
- Release flow → Assets: packages · Uses store screenshots and release metadata
- Release flow → Main app: delivers · Builds and ships the Flutter app
- Android shell → Main app: hosts · Android shell for the Flutter runtime
- iOS shell → Main app: hosts · iOS shell for the Flutter runtime
- Desktop/web shell → Main app: hosts · Desktop and web shells for the Flutter runtime