# stars4422335/biliarchive-pro architecture

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

- Interactive diagram: https://gitdiagram.com/stars4422335/biliarchive-pro
- Repository: https://github.com/stars4422335/biliarchive-pro

## Overview

BiliArchive-Pro is a local Bilibili media-archiving and library-management tool. Its main workflow loads account credentials and configuration, scans configured or discovered sources, parses assets, then downloads and organizes media while recording archive status. A separate WebUI process presents scan and library information and allows limited configuration edits; it does not control downloads. The graph preserves documented article, tombstone, component-check, and UI capabilities. Some subsystem links rely on README documentation because their implementation was not sampled.

Main entry points: [`main.py`](https://github.com/stars4422335/biliarchive-pro/blob/main/main.py) (Runtime orchestrator), [`app/scheduler/scanner.py`](https://github.com/stars4422335/biliarchive-pro/blob/main/app/scheduler/scanner.py) (Source scanner), [`webui/src/App.jsx`](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/App.jsx) (UI application), [`app/core/downloader.py`](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/downloader.py) (Media downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Archive engine"]
  node_login["Account login<br/>[login.py]"]
  node_main["Runtime orchestrator<br/>[main.py]"]
  node_scanner["Source scanner<br/>[scanner.py]"]
end

subgraph group_media["Media processing"]
  node_parser["Source parser<br/>[parser.py]"]
  node_downloader["Media downloader<br/>[downloader.py]"]
  node_metadata["Library metadata<br/>[metadata.py]"]
  node_danmaku["Danmaku renderer<br/>[danmaku.py]"]
  node_pathmanager["Path manager<br/>[path_manager.py]"]
end

subgraph group_state["Configuration and state"]
  node_config["Config manager<br/>[config_manager.py]"]
  node_database[("Archive database")]
  node_runtime["Runtime state<br/>[runtime_state.py]"]
  node_updater["Component updater<br/>[updater.py]"]
  node_secure["Secure file writes<br/>[secure_file.py]"]
end

subgraph group_webbackend["Web API"]
  node_webserver["WebUI API<br/>[app.py]"]
  node_webservice["WebUI service<br/>[service.py]"]
end

subgraph group_webfrontend["Web interface"]
  node_app["UI application<br/>[App.jsx]"]
  node_client["API client<br/>[client.js]"]
  node_normalize["Data normalization<br/>[normalize.js]"]
  node_overview["Overview view<br/>[OverviewView.jsx]"]
  node_assets["Assets view<br/>[AssetsView.jsx]"]
  node_settings["Settings view<br/>[SettingsView.jsx]"]
  node_ui["Shared UI<br/>[ui.jsx]"]
end

node_user(("Archive owner"))
node_bilibili(("Bilibili"))
node_browser(("Browser user"))
node_ytdlp["yt-dlp"]

node_user -->|"authorizes"| node_login
node_login -->|"writes credentials"| node_secure
node_user -->|"starts scans"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"runs scans"| node_scanner
node_main -->|"discovers sources"| node_parser
node_main -->|"updates status"| node_runtime
node_main -->|"checks components"| node_updater
node_scanner -->|"parses sources"| node_parser
node_parser -.->|"reads listings"| node_bilibili
node_scanner -->|"downloads assets"| node_downloader
node_scanner -->|"creates metadata"| node_metadata
node_scanner -.->|"plans paths"| node_pathmanager
node_scanner -.->|"records status"| node_database
node_downloader -->|"renders captions"| node_danmaku
node_downloader -->|"writes temp cookies"| node_secure
node_downloader -.->|"invokes downloader"| node_ytdlp
node_updater -->|"writes verified files"| node_secure
node_main -.->|"starts optional UI"| node_webserver
node_webserver -->|"routes requests"| node_webservice
node_webservice -.->|"reads assets"| node_database
node_webservice -->|"loads configuration"| node_config
node_webservice -->|"writes overrides"| node_secure
node_browser -.->|"uses dashboard"| node_app
node_app -->|"requests API"| node_client
node_app -->|"normalizes responses"| node_normalize
node_app -->|"renders overview"| node_overview
node_app -->|"renders assets"| node_assets
node_app -->|"renders settings"| node_settings
node_overview -->|"loads dashboard"| node_client
node_assets -->|"formats assets"| node_normalize
node_settings -->|"formats settings"| node_normalize
node_overview -->|"uses controls"| node_ui
node_assets -->|"uses controls"| node_ui
node_settings -->|"uses controls"| node_ui
node_client -.->|"calls same-origin API"| node_webserver

click node_login "https://github.com/stars4422335/biliarchive-pro/blob/main/login.py"
click node_main "https://github.com/stars4422335/biliarchive-pro/blob/main/main.py"
click node_scanner "https://github.com/stars4422335/biliarchive-pro/blob/main/app/scheduler/scanner.py"
click node_parser "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/parser.py"
click node_downloader "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/downloader.py"
click node_metadata "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/metadata.py"
click node_danmaku "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/danmaku.py"
click node_pathmanager "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/path_manager.py"
click node_config "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/config_manager.py"
click node_database "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/database_manager.py"
click node_runtime "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/runtime_state.py"
click node_updater "https://github.com/stars4422335/biliarchive-pro/blob/main/app/scheduler/updater.py"
click node_secure "https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/secure_file.py"
click node_webserver "https://github.com/stars4422335/biliarchive-pro/blob/main/app/webui/app.py"
click node_webservice "https://github.com/stars4422335/biliarchive-pro/blob/main/app/webui/service.py"
click node_app "https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/App.jsx"
click node_client "https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/api/client.js"
click node_normalize "https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/data/normalize.js"
click node_overview "https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/views/OverviewView.jsx"
click node_assets "https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/views/AssetsView.jsx"
click node_settings "https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/views/SettingsView.jsx"
click node_ui "https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/components/ui.jsx"

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_login,node_main,node_scanner,node_browser toneBlue
class node_parser,node_downloader,node_metadata,node_danmaku,node_pathmanager toneAmber
class node_config,node_database,node_runtime,node_updater,node_secure toneMint
class node_webserver,node_webservice toneRose
class node_app,node_client,node_normalize,node_overview,node_assets,node_settings,node_ui,node_user,node_bilibili,node_ytdlp toneIndigo
```

## Components

### Archive engine

- [Account login](https://github.com/stars4422335/biliarchive-pro/blob/main/login.py): `login.py`
- [Runtime orchestrator](https://github.com/stars4422335/biliarchive-pro/blob/main/main.py): `main.py`
- [Source scanner](https://github.com/stars4422335/biliarchive-pro/blob/main/app/scheduler/scanner.py): `app/scheduler/scanner.py`

### Media processing

- [Source parser](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/parser.py): `app/core/parser.py`
- [Media downloader](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/downloader.py): `app/core/downloader.py`
- [Library metadata](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/metadata.py): `app/core/metadata.py`
- [Danmaku renderer](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/danmaku.py): `app/core/danmaku.py`
- [Path manager](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/path_manager.py): `app/core/path_manager.py`

### Configuration and state

- [Config manager](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/config_manager.py): `app/core/config_manager.py`
- [Archive database](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/database_manager.py): `app/core/database_manager.py`
- [Runtime state](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/runtime_state.py): `app/core/runtime_state.py`
- [Component updater](https://github.com/stars4422335/biliarchive-pro/blob/main/app/scheduler/updater.py): `app/scheduler/updater.py`
- [Secure file writes](https://github.com/stars4422335/biliarchive-pro/blob/main/app/core/secure_file.py): `app/core/secure_file.py`

### Web API

- [WebUI API](https://github.com/stars4422335/biliarchive-pro/blob/main/app/webui/app.py): `app/webui/app.py`
- [WebUI service](https://github.com/stars4422335/biliarchive-pro/blob/main/app/webui/service.py): `app/webui/service.py`

### Web interface

- [UI application](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/App.jsx): `webui/src/App.jsx`
- [API client](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/api/client.js): `webui/src/api/client.js`
- [Data normalization](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/data/normalize.js): `webui/src/data/normalize.js`
- [Overview view](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/views/OverviewView.jsx): `webui/src/views/OverviewView.jsx`
- [Assets view](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/views/AssetsView.jsx): `webui/src/views/AssetsView.jsx`
- [Settings view](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/views/SettingsView.jsx): `webui/src/views/SettingsView.jsx`
- [Shared UI](https://github.com/stars4422335/biliarchive-pro/blob/main/webui/src/components/ui.jsx): `webui/src/components/ui.jsx`

### Other components

- **Archive owner**
- **Bilibili**
- **Browser user**
- **yt-dlp**

## Connections

- Archive owner → Account login: authorizes (evidence: `README.md`)
- Account login → Secure file writes: writes credentials (evidence: `login.py`)
- Archive owner → Runtime orchestrator: starts scans (evidence: `README.md`)
- Runtime orchestrator → Config manager: loads settings (evidence: `main.py`)
- Runtime orchestrator → Source scanner: runs scans (evidence: `main.py`)
- Runtime orchestrator → Source parser: discovers sources (evidence: `main.py`)
- Runtime orchestrator → Runtime state: updates status (evidence: `main.py`)
- Runtime orchestrator → Component updater: checks components (evidence: `main.py`)
- Source scanner → Source parser: parses sources (evidence: `app/scheduler/scanner.py`)
- Source parser → Bilibili: reads listings
- Source scanner → Media downloader: downloads assets (evidence: `app/scheduler/scanner.py`)
- Source scanner → Library metadata: creates metadata (evidence: `app/scheduler/scanner.py`)
- Source scanner → Path manager: plans paths
- Source scanner → Archive database: records status
- Media downloader → Danmaku renderer: renders captions (evidence: `app/core/downloader.py`)
- Media downloader → Secure file writes: writes temp cookies (evidence: `app/core/downloader.py`)
- Media downloader → yt-dlp: invokes downloader
- Component updater → Secure file writes: writes verified files (evidence: `app/scheduler/updater.py`)
- Runtime orchestrator → WebUI API: starts optional UI (evidence: `main.py`)
- WebUI API → WebUI service: routes requests (evidence: `app/webui/app.py`)
- WebUI service → Archive database: reads assets (evidence: `README.md`)
- WebUI service → Config manager: loads configuration (evidence: `app/webui/service.py`)
- WebUI service → Secure file writes: writes overrides (evidence: `app/webui/service.py`)
- Browser user → UI application: uses dashboard
- UI application → API client: requests API (evidence: `webui/src/App.jsx`)
- UI application → Data normalization: normalizes responses (evidence: `webui/src/App.jsx`)
- UI application → Overview view: renders overview (evidence: `webui/src/App.jsx`)
- UI application → Assets view: renders assets (evidence: `webui/src/App.jsx`)
- UI application → Settings view: renders settings (evidence: `webui/src/App.jsx`)
- Overview view → API client: loads dashboard (evidence: `webui/src/views/OverviewView.jsx`)
- Assets view → Data normalization: formats assets (evidence: `webui/src/views/AssetsView.jsx`)
- Settings view → Data normalization: formats settings (evidence: `webui/src/data/normalize.js`)
- Overview view → Shared UI: uses controls (evidence: `webui/src/views/OverviewView.jsx`)
- Assets view → Shared UI: uses controls (evidence: `webui/src/views/AssetsView.jsx`)
- Settings view → Shared UI: uses controls (evidence: `webui/src/views/SettingsView.jsx`)
- API client → WebUI API: calls same-origin API