# bggrgjqaubcoe/piliplus architecture

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

- Interactive diagram: https://gitdiagram.com/bggrgjqaubcoe/piliplus
- Repository: https://github.com/bggrgjqaubcoe/piliplus

## Overview

#### Purpose and Entrypoints
PiliPlus is a Flutter third-party Bilibili client for Android, iOS, Windows, Linux, and macOS. The Dart application starts at `lib/main.dart`; application routing is centralized in `lib/router/app_pages.dart`. Native host shells bootstrap Flutter per platform, notably `android/app/src/main/kotlin/com/example/piliplus/MainActivity.kt`, `linux/runner/main.cc`, and `windows/runner/main.cpp`.

#### Application Shell, Navigation, and Feature Pages
The app is organized as a large route-driven client: page directories generally pair `controller.dart` with `view.dart`, while shared layouts and reusable UI live separately. Main/tab composition is represented by `lib/pages/main/controller.dart`, `lib/pages/main/view.dart`, and shared shell components such as `lib/common/widgets/main_layout.dart`. Major domains include home/discovery, user/account, dynamic posts, search, live rooms, messaging, favorites, settings, and video.

#### Network and Bilibili API Boundary
REST-like Bilibili interactions are concentrated in `lib/http/`, with API initialization and shared request behavior rooted in `lib/http/init.dart`, `lib/http/api.dart`, and `lib/http/retry_interceptor.dart`. Domain modules such as `lib/http/video.dart`, `lib/http/live.dart`, `lib/http/login.dart`, and `lib/http/dynamics.dart` isolate endpoint operations from page controllers. This is the primary boundary to Bilibili’s external services; requests must handle authentication, signing, retries, and API-specific errors.

#### gRPC Protocol Integration
Generated Bilibili protocol models and hand-written request wrappers form a parallel transport layer under `lib/grpc/`. Core dispatch/request construction is in `lib/grpc/grpc_req.dart`; domain accessors include `lib/grpc/view.dart`, `lib/grpc/reply.dart`, and `lib/grpc/dyn.dart`. Generated protobuf contracts, for example `lib/grpc/bilibili/app/viewunite/v1.pb.dart`, should be treated as generated integration artifacts rather than application-domain code.

#### Account, Session, and Persistent State
Multi-account and cookie/session concerns are encapsulated under `lib/utils/accounts/`, especially `lib/utils/accounts/account_manager/account_mgr.dart`, `lib/utils/accounts/grpc_headers.dart`, and `lib/utils/accounts/cookie_jar_adapter.dart`. General local persistence is abstracted through `lib/utils/storage.dart`, `lib/utils/storage_pref.dart`, and `lib/utils/storage_key.dart`. Page controllers consume these facilities rather than directly managing credentials or storage formats.

#### Media Playback, Danmaku, and Downloads
Playback is a first-class subsystem, centered on the custom player plugin at `lib/plugin/pl_player/controller.dart` and `lib/plugin/pl_player/view/view.dart`. Video orchestration is in `lib/pages/video/controller.dart` and `lib/pages/video/view.dart`; it connects play URLs, settings, subtitles, danmaku, gestures, and content metadata. Background/offline media handling is separated into `lib/services/download/download_manager.dart` and `lib/services/download/download_service.dart`. Platform-specific Android media support exists in `android/app/src/main/java/com/example/piliplus/MediaHelper.java`; shader assets support optional video enhancement under `assets/shaders/`.

#### Data Models and UI Rendering Boundary
Response/domain serialization is split between legacy models in `lib/models/` and broad endpoint-specific DTOs in `lib/models_new/`, e.g. `lib/models_new/video/video_detail/data.dart` and `lib/models_new/live/live_room_play_info/data.dart`. Controllers translate these API models into page state; views render them using common UI primitives from `lib/common/widgets/`. This separation is important because API schemas, transport code, and visual components evolve at different rates.

#### Runtime, Packaging, and Delivery
Flutter/Dart is the shared runtime, with Android Gradle, iOS/macOS Xcode, and Linux/Windows CMake host infrastructure. Android also exposes native helper bridges through `android/app/src/main/java/com/example/piliplus/AndroidHelper.java` and Dart bindings in `lib/utils/android/bindings.g.dart`. CI builds platform artifacts via `.github/workflows/build.yml` and platform workflows. Desktop packaging is explicitly represented by `assets/linux/DEBIAN/control` and `windows/packaging/exe/inno_setup.iss`.

Main entry points: [`lib/grpc/grpc_req.dart`](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/grpc/grpc_req.dart) (gRPC requests), [`lib/router/app_pages.dart`](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/router/app_pages.dart) (App routing), [`lib/http/video.dart`](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/http/video.dart) (REST domain APIs), [`lib/utils/accounts/account_manager/account_mgr.dart`](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/utils/accounts/account_manager/account_mgr.dart) (Account session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter client"]
  node_dart_entry{{"Dart entrypoint<br/>Flutter bootstrap<br/>[main.dart]"}}
  node_routing["App routing<br/>route registry<br/>[app_pages.dart]"]
  node_main_shell["Main shell<br/>tab composition<br/>[view.dart]"]
  node_feature_pages["Feature pages<br/>page controllers and views"]
  node_common_widgets["Common UI<br/>shared widgets<br/>[main_layout.dart]"]
  node_api_models["API models<br/>DTOs and legacy models<br/>[data.dart]"]
end

subgraph group_integration["Bilibili integration"]
  node_api_client{{"REST API client<br/>HTTP boundary<br/>[init.dart]"}}
  node_rest_domains["REST domain APIs<br/>endpoint modules<br/>[video.dart]"]
  node_grpc_requests{{"gRPC requests<br/>protocol dispatcher<br/>[grpc_req.dart]"}}
  node_protobuf_models["Generated protobuf<br/>generated contracts<br/>[v1.pb.dart]"]
  node_account_session["Account session<br/>credentials and cookies<br/>[account_mgr.dart]"]
  node_local_storage[("Local storage<br/>persistence abstraction<br/>[storage.dart]")]
  node_bilibili(("Bilibili services<br/>external API"))
end

subgraph group_media["Media"]
  node_video_page["Video orchestration<br/>video controller and view<br/>[controller.dart]"]
  node_player["Custom player<br/>playback plugin<br/>[controller.dart]"]
  node_downloads["Offline downloads<br/>background media service"]
end

subgraph group_native["Native &amp; delivery"]
  node_native_hosts{{"Platform hosts<br/>Flutter host shells<br/>[MainActivity.kt]"}}
  node_android_media["Android media bridge<br/>native helper<br/>[MediaHelper.java]"]
  node_ci_build["CI builds<br/>artifact pipeline<br/>[build.yml]"]
  node_desktop_packages["Desktop packages<br/>Linux and Windows packaging"]
end

node_native_hosts -->|"boots"| node_dart_entry
node_dart_entry -->|"loads"| node_routing
node_routing -->|"navigates to"| node_main_shell
node_routing -->|"routes to"| node_feature_pages
node_main_shell -->|"composes"| node_common_widgets
node_feature_pages -->|"renders with"| node_common_widgets
node_feature_pages -->|"uses"| node_api_client
node_feature_pages -->|"uses"| node_grpc_requests
node_feature_pages -->|"uses session"| node_account_session
node_feature_pages -->|"persists state"| node_local_storage
node_api_client -->|"hosts"| node_rest_domains
node_rest_domains -->|"calls"| node_bilibili
node_grpc_requests -->|"uses contracts"| node_protobuf_models
node_grpc_requests -->|"calls"| node_bilibili
node_account_session -->|"provides auth"| node_api_client
node_account_session -->|"provides headers"| node_grpc_requests
node_rest_domains -->|"deserializes"| node_api_models
node_grpc_requests -->|"supplies data"| node_api_models
node_api_models -->|"drives state"| node_feature_pages
node_feature_pages -->|"opens"| node_video_page
node_video_page -->|"controls"| node_player
node_video_page -->|"queues offline media"| node_downloads
node_player -.->|"uses on Android"| node_android_media
node_ci_build -->|"produces"| node_desktop_packages

click node_dart_entry "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/main.dart"
click node_routing "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/router/app_pages.dart"
click node_main_shell "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/pages/main/view.dart"
click node_common_widgets "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/common/widgets/main_layout.dart"
click node_api_client "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/http/init.dart"
click node_rest_domains "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/http/video.dart"
click node_grpc_requests "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/grpc/grpc_req.dart"
click node_protobuf_models "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/grpc/bilibili/app/viewunite/v1.pb.dart"
click node_account_session "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/utils/accounts/account_manager/account_mgr.dart"
click node_local_storage "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/utils/storage.dart"
click node_api_models "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/models_new/video/video_detail/data.dart"
click node_video_page "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/pages/video/controller.dart"
click node_player "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/plugin/pl_player/controller.dart"
click node_downloads "https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/services/download/download_manager.dart"
click node_native_hosts "https://github.com/bggrgjqaubcoe/piliplus/blob/main/android/app/src/main/kotlin/com/example/piliplus/MainActivity.kt"
click node_android_media "https://github.com/bggrgjqaubcoe/piliplus/blob/main/android/app/src/main/java/com/example/piliplus/MediaHelper.java"
click node_ci_build "https://github.com/bggrgjqaubcoe/piliplus/blob/main/.github/workflows/build.yml"
click node_desktop_packages "https://github.com/bggrgjqaubcoe/piliplus/blob/main/assets/linux/DEBIAN/control"

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_dart_entry,node_routing,node_main_shell,node_feature_pages,node_common_widgets,node_api_models toneBlue
class node_api_client,node_rest_domains,node_grpc_requests,node_protobuf_models,node_account_session,node_local_storage,node_bilibili toneAmber
class node_video_page,node_player,node_downloads toneMint
class node_native_hosts,node_android_media,node_ci_build,node_desktop_packages toneRose
```

## Components

### Flutter client

- [Dart entrypoint](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/main.dart): Flutter bootstrap · `lib/main.dart`
- [App routing](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/router/app_pages.dart): route registry · `lib/router/app_pages.dart`
- [Main shell](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/pages/main/view.dart): tab composition · `lib/pages/main/view.dart`
- **Feature pages**: page controllers and views · Home, account, dynamics, search, live, messaging, favorites, settings, and video.
- [Common UI](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/common/widgets/main_layout.dart): shared widgets · `lib/common/widgets/main_layout.dart`
- [API models](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/models_new/video/video_detail/data.dart): DTOs and legacy models · Controllers translate API schemas into page state. · `lib/models_new/video/video_detail/data.dart`

### Bilibili integration

- [REST API client](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/http/init.dart): HTTP boundary · Initializes shared request behavior and API access. · `lib/http/init.dart`
- [REST domain APIs](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/http/video.dart): endpoint modules · Video, live, login, and dynamics operations. · `lib/http/video.dart`
- [gRPC requests](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/grpc/grpc_req.dart): protocol dispatcher · `lib/grpc/grpc_req.dart`
- [Generated protobuf](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/grpc/bilibili/app/viewunite/v1.pb.dart): generated contracts · `lib/grpc/bilibili/app/viewunite/v1.pb.dart`
- [Account session](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/utils/accounts/account_manager/account_mgr.dart): credentials and cookies · `lib/utils/accounts/account_manager/account_mgr.dart`
- [Local storage](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/utils/storage.dart): persistence abstraction · `lib/utils/storage.dart`
- **Bilibili services**: external API · Authentication, signing, API errors, and content endpoints.

### Media

- [Video orchestration](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/pages/video/controller.dart): video controller and view · `lib/pages/video/controller.dart`
- [Custom player](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/plugin/pl_player/controller.dart): playback plugin · `lib/plugin/pl_player/controller.dart`
- [Offline downloads](https://github.com/bggrgjqaubcoe/piliplus/blob/main/lib/services/download/download_manager.dart): background media service · `lib/services/download/download_manager.dart`

### Native & delivery

- [Platform hosts](https://github.com/bggrgjqaubcoe/piliplus/blob/main/android/app/src/main/kotlin/com/example/piliplus/MainActivity.kt): Flutter host shells · Android, Linux, and Windows bootstrap Flutter. · `android/app/src/main/kotlin/com/example/piliplus/MainActivity.kt`
- [Android media bridge](https://github.com/bggrgjqaubcoe/piliplus/blob/main/android/app/src/main/java/com/example/piliplus/MediaHelper.java): native helper · `android/app/src/main/java/com/example/piliplus/MediaHelper.java`
- [CI builds](https://github.com/bggrgjqaubcoe/piliplus/blob/main/.github/workflows/build.yml): artifact pipeline · `.github/workflows/build.yml`
- [Desktop packages](https://github.com/bggrgjqaubcoe/piliplus/blob/main/assets/linux/DEBIAN/control): Linux and Windows packaging · `assets/linux/DEBIAN/control`

## Connections

- Platform hosts → Dart entrypoint: boots
- Dart entrypoint → App routing: loads
- App routing → Main shell: navigates to
- App routing → Feature pages: routes to
- Main shell → Common UI: composes
- Feature pages → Common UI: renders with
- Feature pages → REST API client: uses
- Feature pages → gRPC requests: uses
- Feature pages → Account session: uses session
- Feature pages → Local storage: persists state
- REST API client → REST domain APIs: hosts
- REST domain APIs → Bilibili services: calls
- gRPC requests → Generated protobuf: uses contracts
- gRPC requests → Bilibili services: calls
- Account session → REST API client: provides auth
- Account session → gRPC requests: provides headers
- REST domain APIs → API models: deserializes
- gRPC requests → API models: supplies data
- API models → Feature pages: drives state
- Feature pages → Video orchestration: opens
- Video orchestration → Custom player: controls
- Video orchestration → Offline downloads: queues offline media
- Custom player → Android media bridge: uses on Android
- CI builds → Desktop packages: produces