# keleus/bewlycat architecture

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

- Interactive diagram: https://gitdiagram.com/keleus/bewlycat
- Repository: https://github.com/keleus/bewlycat

## Overview

BewlyCat is a browser extension that customizes Bilibili’s website with redesigned pages, navigation, settings, and playback enhancements. The main user workflow is: visit Bilibili, load the extension’s content-script experience, browse home/search and other content pages, and use API-backed controls and persistent preferences. Separate branches cover the top bar, settings and cloud synchronization, and player/page enhancements. The tree and README establish these capabilities; some subsystem links are documented rather than confirmed from sampled implementation, so those edges are marked dashed with no evidence path.

Main entry points: [`src/contentScripts/views/App.vue`](https://github.com/keleus/bewlycat/blob/main/src/contentScripts/views/App.vue) (Extension app shell), [`src/contentScripts/index.ts`](https://github.com/keleus/bewlycat/blob/main/src/contentScripts/index.ts) (Content-script host), [`src/utils/api.ts`](https://github.com/keleus/bewlycat/blob/main/src/utils/api.ts) (API client), [`src/inject/index.ts`](https://github.com/keleus/bewlycat/blob/main/src/inject/index.ts) (Player enhancements)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Page experience"]
  node_content_host["Content-script host<br/>[index.ts]"]
  node_app_shell["Extension app shell<br/>[App.vue]"]
  node_home["Home feed<br/>[Home.vue]"]
  node_search["Search pages"]
  node_moments["Moments feed<br/>[Moments.vue]"]
  node_video_cards["Video cards<br/>[VideoCard.vue]"]
end

subgraph group_navigation["Navigation"]
  node_topbar["Custom top bar<br/>[TopBar.vue]"]
  node_topbar_state["Top-bar state<br/>[topBarStore.ts]"]
end

subgraph group_services["Data services"]
  node_api_client["API client<br/>[api.ts]"]
  node_background["Background worker<br/>[index.ts]"]
  node_api_handlers["API handlers"]
end

subgraph group_preferences["Settings and state"]
  node_settings_ui["Settings screens<br/>[Settings.vue]"]
  node_settings_storage[("Settings storage<br/>[storage.ts]")]
  node_storage_composable["Settings persistence"]
  node_storage_coordinator["Storage coordinator"]
  node_cloud_protocol["Cloud sync protocol"]
end

subgraph group_enhancements["Site enhancements"]
  node_player_features["Player enhancements<br/>[index.ts]"]
  node_content_features["Page enhancements"]
  node_loudness["Local loudness<br/>[localLoudness.ts]"]
end

node_visitor(("Bilibili visitor"))
node_website["Bilibili website"]

node_visitor -->|"visits"| node_website
node_website -.->|"hosts extension"| node_content_host
node_content_host -.->|"mounts"| node_app_shell
node_app_shell -.->|"shows pages"| node_home
node_app_shell -.->|"shows pages"| node_search
node_app_shell -.->|"shows pages"| node_moments
node_home -.->|"renders"| node_video_cards
node_app_shell -.->|"shows navigation"| node_topbar
node_topbar -->|"uses state"| node_topbar_state
node_video_cards -->|"requests data"| node_api_client
node_api_client -->|"sends messages"| node_background
node_background -->|"registers handlers"| node_api_handlers
node_search -->|"requests results"| node_api_client
node_settings_ui -.->|"configures"| node_settings_storage
node_settings_storage -->|"persists settings"| node_storage_composable
node_storage_composable -->|"sends patches"| node_storage_coordinator
node_storage_coordinator -->|"uses sync protocol"| node_cloud_protocol
node_content_host -.->|"enables enhancements"| node_content_features
node_content_host -.->|"integrates player controls"| node_player_features
node_player_features -->|"uses audio module"| node_loudness
node_website -.->|"receives playback changes"| node_player_features

click node_content_host "https://github.com/keleus/bewlycat/blob/main/src/contentScripts/index.ts"
click node_app_shell "https://github.com/keleus/bewlycat/blob/main/src/contentScripts/views/App.vue"
click node_home "https://github.com/keleus/bewlycat/blob/main/src/contentScripts/views/Home/Home.vue"
click node_search "https://github.com/keleus/bewlycat/tree/main/src/contentScripts/views/SearchResults"
click node_moments "https://github.com/keleus/bewlycat/blob/main/src/contentScripts/views/Moments/Moments.vue"
click node_video_cards "https://github.com/keleus/bewlycat/blob/main/src/components/VideoCard/VideoCard.vue"
click node_topbar "https://github.com/keleus/bewlycat/blob/main/src/components/TopBar/TopBar.vue"
click node_topbar_state "https://github.com/keleus/bewlycat/blob/main/src/stores/topBarStore.ts"
click node_api_client "https://github.com/keleus/bewlycat/blob/main/src/utils/api.ts"
click node_background "https://github.com/keleus/bewlycat/blob/main/src/background/index.ts"
click node_api_handlers "https://github.com/keleus/bewlycat/tree/main/src/background/messageListeners/api"
click node_settings_ui "https://github.com/keleus/bewlycat/blob/main/src/components/Settings/Settings.vue"
click node_settings_storage "https://github.com/keleus/bewlycat/blob/main/src/logic/storage.ts"
click node_storage_composable "https://github.com/keleus/bewlycat/blob/main/src/composables/useSettingsStorage.ts"
click node_storage_coordinator "https://github.com/keleus/bewlycat/blob/main/src/background/settingsStorageCoordinator.ts"
click node_cloud_protocol "https://github.com/keleus/bewlycat/blob/main/src/utils/settingsCloudSyncProtocol.ts"
click node_player_features "https://github.com/keleus/bewlycat/blob/main/src/inject/index.ts"
click node_content_features "https://github.com/keleus/bewlycat/tree/main/src/contentScripts/features"
click node_loudness "https://github.com/keleus/bewlycat/blob/main/src/inject/audio/localLoudness.ts"

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_content_host,node_app_shell,node_home,node_search,node_moments,node_video_cards toneBlue
class node_topbar,node_topbar_state toneAmber
class node_api_client,node_background,node_api_handlers toneMint
class node_settings_ui,node_settings_storage,node_storage_composable,node_storage_coordinator,node_cloud_protocol toneRose
class node_player_features,node_content_features,node_loudness,node_visitor,node_website toneIndigo
```

## Components

### Page experience

- [Content-script host](https://github.com/keleus/bewlycat/blob/main/src/contentScripts/index.ts): `src/contentScripts/index.ts`
- [Extension app shell](https://github.com/keleus/bewlycat/blob/main/src/contentScripts/views/App.vue): `src/contentScripts/views/App.vue`
- [Home feed](https://github.com/keleus/bewlycat/blob/main/src/contentScripts/views/Home/Home.vue): `src/contentScripts/views/Home/Home.vue`
- [Search pages](https://github.com/keleus/bewlycat/tree/main/src/contentScripts/views/SearchResults): `src/contentScripts/views/SearchResults`
- [Moments feed](https://github.com/keleus/bewlycat/blob/main/src/contentScripts/views/Moments/Moments.vue): `src/contentScripts/views/Moments/Moments.vue`
- [Video cards](https://github.com/keleus/bewlycat/blob/main/src/components/VideoCard/VideoCard.vue): `src/components/VideoCard/VideoCard.vue`

### Navigation

- [Custom top bar](https://github.com/keleus/bewlycat/blob/main/src/components/TopBar/TopBar.vue): `src/components/TopBar/TopBar.vue`
- [Top-bar state](https://github.com/keleus/bewlycat/blob/main/src/stores/topBarStore.ts): `src/stores/topBarStore.ts`

### Data services

- [API client](https://github.com/keleus/bewlycat/blob/main/src/utils/api.ts): `src/utils/api.ts`
- [Background worker](https://github.com/keleus/bewlycat/blob/main/src/background/index.ts): `src/background/index.ts`
- [API handlers](https://github.com/keleus/bewlycat/tree/main/src/background/messageListeners/api): `src/background/messageListeners/api`

### Settings and state

- [Settings screens](https://github.com/keleus/bewlycat/blob/main/src/components/Settings/Settings.vue): `src/components/Settings/Settings.vue`
- [Settings storage](https://github.com/keleus/bewlycat/blob/main/src/logic/storage.ts): `src/logic/storage.ts`
- [Settings persistence](https://github.com/keleus/bewlycat/blob/main/src/composables/useSettingsStorage.ts): `src/composables/useSettingsStorage.ts`
- [Storage coordinator](https://github.com/keleus/bewlycat/blob/main/src/background/settingsStorageCoordinator.ts): `src/background/settingsStorageCoordinator.ts`
- [Cloud sync protocol](https://github.com/keleus/bewlycat/blob/main/src/utils/settingsCloudSyncProtocol.ts): `src/utils/settingsCloudSyncProtocol.ts`

### Site enhancements

- [Player enhancements](https://github.com/keleus/bewlycat/blob/main/src/inject/index.ts): `src/inject/index.ts`
- [Page enhancements](https://github.com/keleus/bewlycat/tree/main/src/contentScripts/features): `src/contentScripts/features`
- [Local loudness](https://github.com/keleus/bewlycat/blob/main/src/inject/audio/localLoudness.ts): `src/inject/audio/localLoudness.ts`

### Other components

- **Bilibili visitor**
- **Bilibili website**

## Connections

- Bilibili visitor → Bilibili website: visits (evidence: `README.md`)
- Bilibili website → Content-script host: hosts extension
- Content-script host → Extension app shell: mounts
- Extension app shell → Home feed: shows pages (evidence: `src/contentScripts/views/App.vue`)
- Extension app shell → Search pages: shows pages (evidence: `src/contentScripts/views/App.vue`)
- Extension app shell → Moments feed: shows pages (evidence: `src/contentScripts/views/App.vue`)
- Home feed → Video cards: renders
- Extension app shell → Custom top bar: shows navigation
- Custom top bar → Top-bar state: uses state
- Video cards → API client: requests data
- API client → Background worker: sends messages
- Background worker → API handlers: registers handlers (evidence: `src/background/index.ts`)
- Search pages → API client: requests results (evidence: `src/contentScripts/views/SearchResults/composables/useSearchRequest.ts`)
- Settings screens → Settings storage: configures
- Settings storage → Settings persistence: persists settings (evidence: `src/logic/storage.ts`)
- Settings persistence → Storage coordinator: sends patches (evidence: `src/composables/useSettingsStorage.ts`)
- Storage coordinator → Cloud sync protocol: uses sync protocol (evidence: `src/background/settingsStorageCoordinator.ts`)
- Content-script host → Page enhancements: enables enhancements (evidence: `src/contentScripts/index.ts`)
- Content-script host → Player enhancements: integrates player controls
- Player enhancements → Local loudness: uses audio module (evidence: `src/inject/index.ts`)
- Bilibili website → Player enhancements: receives playback changes