# whiteguo233/openbiliclaw architecture

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

- Interactive diagram: https://gitdiagram.com/whiteguo233/openbiliclaw
- Repository: https://github.com/whiteguo233/openbiliclaw

## Overview

OpenBiliClaw is a local, cross-platform content-discovery agent. The principal workflow is that browser activity and feedback reach the local backend, inform a persistent user profile, guide cross-platform discovery and recommendation, and are refined by further feedback. The graph also shows the web client, LLM service, saved-content sync, and agent tools as meaningful product capabilities. The README supports the product-level flow; source excerpts and index references support selected internal relationships. Unsampled runtime wiring is not asserted.

Main entry points: [`src/openbiliclaw/memory/manager.py`](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/memory/manager.py) (Memory manager), [`src/openbiliclaw/soul/profile.py`](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/soul/profile.py) (User profile), [`src/openbiliclaw/recommendation/engine.py`](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/recommendation/engine.py) (Recommendation engine), [`src/openbiliclaw/runtime/event_ingress.py`](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/runtime/event_ingress.py) (Event ingress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_extension["Browser extension<br/>[service-worker.ts]"]
  node_web["Web interface<br/>[app.js]"]
end

subgraph group_runtime["Backend runtime"]
  node_api["Local API<br/>[app.py]"]
  node_agent["Agent tools<br/>[orchestrator.py]"]
  node_event_ingress["Event ingress<br/>[event_ingress.py]"]
  node_llm["LLM service<br/>[service.py]"]
end

subgraph group_learning["Profile learning"]
  node_memory["Memory manager<br/>[manager.py]"]
  node_soul_pipeline["Profile update<br/>[pipeline.py]"]
  node_soul_engine["Profile analysis<br/>[engine.py]"]
  node_profile["User profile<br/>[profile.py]"]
end

subgraph group_discovery["Content discovery"]
  node_inspiration["Inspiration pipeline"]
  node_discovery_engine["Discovery engine<br/>[engine.py]"]
  node_candidate_pipeline["Candidate evaluation"]
  node_recommendation["Recommendation engine<br/>[engine.py]"]
end

subgraph group_platform["Platform and persistence"]
  node_source_registry["Source registry<br/>[registry.py]"]
  node_database[("Local database<br/>[database.py]")]
  node_saved_sync["Saved content sync<br/>[service.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_extension
node_extension -->|"sends activity"| node_api
node_user -->|"uses"| node_web
node_web -->|"calls local API"| node_api
node_api -.->|"routes events"| node_event_ingress
node_event_ingress -.->|"attributes sources"| node_source_registry
node_event_ingress -.->|"records signals"| node_memory
node_memory -->|"persists events"| node_database
node_memory -.->|"updates profile"| node_soul_pipeline
node_soul_pipeline -->|"builds profile"| node_profile
node_soul_engine -->|"reads memory"| node_memory
node_soul_engine -->|"analyzes signals"| node_llm
node_inspiration -->|"uses interests"| node_profile
node_discovery_engine -->|"matches content"| node_profile
node_discovery_engine -->|"evaluates candidates"| node_candidate_pipeline
node_recommendation -->|"uses discoveries"| node_discovery_engine
node_recommendation -->|"personalizes results"| node_profile
node_recommendation -->|"presents results"| node_user
node_user -->|"gives feedback"| node_soul_pipeline
node_agent -.->|"accesses memory"| node_memory
node_saved_sync -->|"uses storage"| node_database

click node_extension "https://github.com/whiteguo233/openbiliclaw/blob/main/extension/src/background/service-worker.ts"
click node_web "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/web/js/app.js"
click node_api "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/api/app.py"
click node_agent "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/agent/orchestrator.py"
click node_event_ingress "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/runtime/event_ingress.py"
click node_source_registry "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/sources/registry.py"
click node_memory "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/memory/manager.py"
click node_soul_pipeline "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/soul/pipeline.py"
click node_soul_engine "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/soul/engine.py"
click node_profile "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/soul/profile.py"
click node_inspiration "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/runtime/inspiration_pipeline.py"
click node_discovery_engine "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/discovery/engine.py"
click node_candidate_pipeline "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/discovery/candidate_pipeline.py"
click node_recommendation "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/recommendation/engine.py"
click node_llm "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/llm/service.py"
click node_database "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/storage/database.py"
click node_saved_sync "https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/saved_sync/service.py"

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_extension,node_web,node_user toneBlue
class node_api,node_agent,node_event_ingress,node_llm toneAmber
class node_memory,node_soul_pipeline,node_soul_engine,node_profile toneMint
class node_inspiration,node_discovery_engine,node_candidate_pipeline,node_recommendation toneRose
class node_source_registry,node_database,node_saved_sync toneIndigo
```

## Components

### User interfaces

- [Browser extension](https://github.com/whiteguo233/openbiliclaw/blob/main/extension/src/background/service-worker.ts): `extension/src/background/service-worker.ts`
- [Web interface](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/web/js/app.js): `src/openbiliclaw/web/js/app.js`

### Backend runtime

- [Local API](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/api/app.py): `src/openbiliclaw/api/app.py`
- [Agent tools](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/agent/orchestrator.py): `src/openbiliclaw/agent/orchestrator.py`
- [Event ingress](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/runtime/event_ingress.py): `src/openbiliclaw/runtime/event_ingress.py`
- [LLM service](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/llm/service.py): `src/openbiliclaw/llm/service.py`

### Profile learning

- [Memory manager](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/memory/manager.py): `src/openbiliclaw/memory/manager.py`
- [Profile update](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/soul/pipeline.py): `src/openbiliclaw/soul/pipeline.py`
- [Profile analysis](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/soul/engine.py): `src/openbiliclaw/soul/engine.py`
- [User profile](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/soul/profile.py): `src/openbiliclaw/soul/profile.py`

### Content discovery

- [Inspiration pipeline](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/runtime/inspiration_pipeline.py): `src/openbiliclaw/runtime/inspiration_pipeline.py`
- [Discovery engine](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/discovery/engine.py): `src/openbiliclaw/discovery/engine.py`
- [Candidate evaluation](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/discovery/candidate_pipeline.py): `src/openbiliclaw/discovery/candidate_pipeline.py`
- [Recommendation engine](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/recommendation/engine.py): `src/openbiliclaw/recommendation/engine.py`

### Platform and persistence

- [Source registry](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/sources/registry.py): `src/openbiliclaw/sources/registry.py`
- [Local database](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/storage/database.py): `src/openbiliclaw/storage/database.py`
- [Saved content sync](https://github.com/whiteguo233/openbiliclaw/blob/main/src/openbiliclaw/saved_sync/service.py): `src/openbiliclaw/saved_sync/service.py`

### Other components

- **User**

## Connections

- User → Browser extension: uses (evidence: `README.md`)
- Browser extension → Local API: sends activity (evidence: `README.md`)
- User → Web interface: uses (evidence: `README.md`)
- Web interface → Local API: calls local API (evidence: `README.md`)
- Local API → Event ingress: routes events
- Event ingress → Source registry: attributes sources
- Event ingress → Memory manager: records signals
- Memory manager → Local database: persists events (evidence: `src/openbiliclaw/memory/manager.py`)
- Memory manager → Profile update: updates profile (evidence: `src/openbiliclaw/soul/pipeline.py`)
- Profile update → User profile: builds profile (evidence: `src/openbiliclaw/soul/pipeline.py`)
- Profile analysis → Memory manager: reads memory (evidence: `src/openbiliclaw/soul/engine.py`)
- Profile analysis → LLM service: analyzes signals (evidence: `src/openbiliclaw/soul/engine.py`)
- Inspiration pipeline → User profile: uses interests (evidence: `src/openbiliclaw/runtime/inspiration_pipeline.py`)
- Discovery engine → User profile: matches content (evidence: `src/openbiliclaw/discovery/engine.py`)
- Discovery engine → Candidate evaluation: evaluates candidates (evidence: `src/openbiliclaw/discovery/engine.py`)
- Recommendation engine → Discovery engine: uses discoveries (evidence: `src/openbiliclaw/recommendation/engine.py`)
- Recommendation engine → User profile: personalizes results (evidence: `src/openbiliclaw/recommendation/engine.py`)
- Recommendation engine → User: presents results (evidence: `README.md`)
- User → Profile update: gives feedback (evidence: `README.md`)
- Agent tools → Memory manager: accesses memory
- Saved content sync → Local database: uses storage (evidence: `src/openbiliclaw/saved_sync/service.py`)
