# lifeisastory/my_pilipala architecture

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

- Interactive diagram: https://gitdiagram.com/lifeisastory/my_pilipala
- Repository: https://github.com/lifeisastory/my_pilipala

## Overview

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: [`lib/router/app_pages.dart`](https://github.com/lifeisastory/my_pilipala/blob/main/lib/router/app_pages.dart) (App routes), [`lib/http/index.dart`](https://github.com/lifeisastory/my_pilipala/blob/main/lib/http/index.dart) (HTTP API), [`lib/main.dart`](https://github.com/lifeisastory/my_pilipala/blob/main/lib/main.dart) (Main app), [`lib/pages/video/detail/index.dart`](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/video/detail/index.dart) (Video detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Flutter app"]
  node_n_main["Main app<br/>Flutter entry<br/>[main.dart]"]
  node_n_router["App routes<br/>Navigation<br/>[app_pages.dart]"]
  node_n_android["Android shell<br/>Platform host"]
  node_n_ios["iOS shell<br/>Platform host<br/>[AppDelegate.swift]"]
  node_n_desktop["Desktop/web shell<br/>Platform host<br/>[main.cc]"]
end

subgraph group_grp_features["Feature pages"]
  node_n_home["Home feed<br/>Discovery pages<br/>[index.dart]"]
  node_n_search["Search flow<br/>Search pages<br/>[index.dart]"]
  node_n_video["Video detail<br/>Playback pages<br/>[index.dart]"]
  node_n_live["Live room<br/>Playback pages<br/>[index.dart]"]
  node_n_social["Social hub<br/>Account pages<br/>[index.dart]"]
  node_n_library["Library pages<br/>Personal pages<br/>[index.dart]"]
  node_n_settings["Settings<br/>Preferences pages<br/>[index.dart]"]
end

subgraph group_grp_data["Data layer"]
  node_n_api["HTTP API<br/>Network boundary<br/>[index.dart]"]
  node_n_models["Domain models<br/>Typed models<br/>[index.dart]"]
  node_n_storage[("Local state<br/>Persistence<br/>[storage.dart]")]
end

subgraph group_grp_runtime["Shared runtime"]
  node_n_player["Player core<br/>Media plugin<br/>[index.dart]"]
  node_n_gallery["Gallery UI<br/>Media plugin<br/>[index.dart]"]
  node_n_socket["Realtime socket<br/>Realtime plugin<br/>[index.dart]"]
  node_n_services["App services<br/>Runtime services"]
  node_n_common["Shared UI<br/>Widgets<br/>[appbar.dart]"]
  node_n_utils["App utils<br/>Cross-cutting helpers<br/>[utils.dart]"]
end

subgraph group_grp_delivery["Delivery"]
  node_n_assets["Assets<br/>Static resources"]
  node_n_release["Release flow<br/>CI/CD<br/>[release_ci.yml]"]
end

node_n_main -->|"uses"| node_n_router
node_n_main -->|"launches"| node_n_home
node_n_router -->|"routes"| node_n_home
node_n_router -->|"routes"| node_n_search
node_n_router -->|"routes"| node_n_video
node_n_router -->|"routes"| node_n_live
node_n_router -->|"routes"| node_n_social
node_n_router -->|"routes"| node_n_library
node_n_router -->|"routes"| node_n_settings
node_n_home -->|"fetches"| node_n_api
node_n_search -->|"fetches"| node_n_api
node_n_video -->|"fetches"| node_n_api
node_n_live -->|"fetches"| node_n_api
node_n_social -->|"fetches"| node_n_api
node_n_library -->|"fetches"| node_n_api
node_n_api -->|"parses"| node_n_models
node_n_api -->|"auth/state"| node_n_storage
node_n_video -->|"plays"| node_n_player
node_n_live -->|"plays"| node_n_player
node_n_video -->|"renders"| node_n_common
node_n_home -->|"renders"| node_n_common
node_n_search -->|"renders"| node_n_common
node_n_social -->|"realtime"| node_n_socket
node_n_video -->|"helpers"| node_n_utils
node_n_services -->|"supports"| node_n_player
node_n_services -->|"supports"| node_n_storage
node_n_common -->|"loads"| node_n_assets
node_n_release -->|"packages"| node_n_assets
node_n_release -.->|"delivers"| node_n_main
node_n_android -.->|"hosts"| node_n_main
node_n_ios -.->|"hosts"| node_n_main
node_n_desktop -.->|"hosts"| node_n_main

click node_n_main "https://github.com/lifeisastory/my_pilipala/blob/main/lib/main.dart"
click node_n_router "https://github.com/lifeisastory/my_pilipala/blob/main/lib/router/app_pages.dart"
click node_n_home "https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/home/index.dart"
click node_n_search "https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/search/index.dart"
click node_n_video "https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/video/detail/index.dart"
click node_n_live "https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/live_room/index.dart"
click node_n_social "https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/login/index.dart"
click node_n_library "https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/history/index.dart"
click node_n_settings "https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/setting/index.dart"
click node_n_api "https://github.com/lifeisastory/my_pilipala/blob/main/lib/http/index.dart"
click node_n_models "https://github.com/lifeisastory/my_pilipala/blob/main/lib/models/common/index.dart"
click node_n_storage "https://github.com/lifeisastory/my_pilipala/blob/main/lib/utils/storage.dart"
click node_n_player "https://github.com/lifeisastory/my_pilipala/blob/main/lib/plugin/pl_player/index.dart"
click node_n_gallery "https://github.com/lifeisastory/my_pilipala/blob/main/lib/plugin/pl_gallery/index.dart"
click node_n_socket "https://github.com/lifeisastory/my_pilipala/blob/main/lib/plugin/pl_socket/index.dart"
click node_n_services "https://github.com/lifeisastory/my_pilipala/blob/main/lib/services/service_locator.dart"
click node_n_common "https://github.com/lifeisastory/my_pilipala/blob/main/lib/common/widgets/appbar.dart"
click node_n_utils "https://github.com/lifeisastory/my_pilipala/blob/main/lib/utils/utils.dart"
click node_n_assets "https://github.com/lifeisastory/my_pilipala/tree/main/assets"
click node_n_release "https://github.com/lifeisastory/my_pilipala/blob/main/.github/workflows/release_ci.yml"
click node_n_android "https://github.com/lifeisastory/my_pilipala/blob/main/android/app/src/main/AndroidManifest.xml"
click node_n_ios "https://github.com/lifeisastory/my_pilipala/blob/main/ios/Runner/AppDelegate.swift"
click node_n_desktop "https://github.com/lifeisastory/my_pilipala/blob/main/linux/main.cc"

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_n_main,node_n_router,node_n_android,node_n_ios,node_n_desktop toneBlue
class node_n_home,node_n_search,node_n_video,node_n_live,node_n_social,node_n_library,node_n_settings toneAmber
class node_n_api,node_n_models,node_n_storage toneMint
class node_n_player,node_n_gallery,node_n_socket,node_n_services,node_n_common,node_n_utils toneRose
class node_n_assets,node_n_release toneIndigo
```

## Components

### Flutter app

Single Flutter codebase and native shells

- [Main app](https://github.com/lifeisastory/my_pilipala/blob/main/lib/main.dart): Flutter entry · App bootstrap, routing, and top-level composition · `lib/main.dart`
- [App routes](https://github.com/lifeisastory/my_pilipala/blob/main/lib/router/app_pages.dart): Navigation · Central route map for page navigation · `lib/router/app_pages.dart`
- [Android shell](https://github.com/lifeisastory/my_pilipala/blob/main/android/app/src/main/AndroidManifest.xml): Platform host · Native Android packaging and launch shell · `android/app/src/main/AndroidManifest.xml`
- [iOS shell](https://github.com/lifeisastory/my_pilipala/blob/main/ios/Runner/AppDelegate.swift): Platform host · Native iOS packaging and launch shell · `ios/Runner/AppDelegate.swift`
- [Desktop/web shell](https://github.com/lifeisastory/my_pilipala/blob/main/linux/main.cc): Platform host · Linux, macOS, Windows, and web host shells · `linux/main.cc`

### Feature pages

Page-based user-facing modules

- [Home feed](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/home/index.dart): Discovery pages · Landing feed and primary content discovery surface · `lib/pages/home/index.dart`
- [Search flow](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/search/index.dart): Search pages · Search entry, panels, and results · `lib/pages/search/index.dart`
- [Video detail](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/video/detail/index.dart): Playback pages · Video detail orchestration, related content, and replies · `lib/pages/video/detail/index.dart`
- [Live room](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/live_room/index.dart): Playback pages · Live-room viewing and controls · `lib/pages/live_room/index.dart`
- [Social hub](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/login/index.dart): Account pages · Login, member, follow/fan, message, and whisper flows · `lib/pages/login/index.dart`
- [Library pages](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/history/index.dart): Personal pages · History, later, favorites, subscriptions, and profile area · `lib/pages/history/index.dart`
- [Settings](https://github.com/lifeisastory/my_pilipala/blob/main/lib/pages/setting/index.dart): Preferences pages · Playback, style, privacy, navigation, and log settings · `lib/pages/setting/index.dart`

### Data layer

Remote API, models, and local persistence

- [HTTP API](https://github.com/lifeisastory/my_pilipala/blob/main/lib/http/index.dart): Network boundary · Domain-specific API wrappers for BiliBili endpoints · `lib/http/index.dart`
- [Domain models](https://github.com/lifeisastory/my_pilipala/blob/main/lib/models/common/index.dart): Typed models · Strongly typed response and app state models, including danmaku protobufs · `lib/models/common/index.dart`
- [Local state](https://github.com/lifeisastory/my_pilipala/blob/main/lib/utils/storage.dart): Persistence · Cookies, storage, cache, login/session, and other device state helpers · `lib/utils/storage.dart`

### Shared runtime

Reusable widgets, plugins, services, and utilities

- [Player core](https://github.com/lifeisastory/my_pilipala/blob/main/lib/plugin/pl_player/index.dart): Media plugin · Custom playback UI, controls, and playback state management · `lib/plugin/pl_player/index.dart`
- [Gallery UI](https://github.com/lifeisastory/my_pilipala/blob/main/lib/plugin/pl_gallery/index.dart): Media plugin · Image preview and hero/interactive gallery interactions · `lib/plugin/pl_gallery/index.dart`
- [Realtime socket](https://github.com/lifeisastory/my_pilipala/blob/main/lib/plugin/pl_socket/index.dart): Realtime plugin · Socket-based live or messaging interactions · `lib/plugin/pl_socket/index.dart`
- [App services](https://github.com/lifeisastory/my_pilipala/blob/main/lib/services/service_locator.dart): Runtime services · Audio, battery, shutdown timer, logging, and service locator · `lib/services/service_locator.dart`
- [Shared UI](https://github.com/lifeisastory/my_pilipala/blob/main/lib/common/widgets/appbar.dart): Widgets · Reusable cards, skeletons, app bars, errors, empty states, and HTML rendering · `lib/common/widgets/appbar.dart`
- [App utils](https://github.com/lifeisastory/my_pilipala/blob/main/lib/utils/utils.dart): Cross-cutting helpers · URL, auth, event bus, recommendation, media, download, and route helpers · `lib/utils/utils.dart`

### Delivery

Assets, release metadata, and CI workflows

- [Assets](https://github.com/lifeisastory/my_pilipala/tree/main/assets): Static resources · Fonts, images, loading animations, and screenshots · `assets`
- [Release flow](https://github.com/lifeisastory/my_pilipala/blob/main/.github/workflows/release_ci.yml): CI/CD · Fastlane metadata, changelogs, and GitHub workflows for build and release · `.github/workflows/release_ci.yml`

## Connections

- 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
