# tswawa/wechatvibe architecture

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

- Interactive diagram: https://gitdiagram.com/tswawa/wechatvibe
- Repository: https://github.com/tswawa/wechatvibe

## Overview

WechatVibe is a Windows WeChat chat-analysis client. Users select conversations, inspect history, request message emotion/intent labels, and review saved individual or group portraits. The documented runtime spans the chat UI, a Python application service, read-only WeChat data access, and local Laya or configured API analysis. The README documents those product capabilities; source-index references and excerpts support the internal links shown. The HTTP/UI wiring and several capability modules were not sampled, so those links are omitted or marked unverified.

Main entry points: [`bridge/backend_service.py`](https://github.com/tswawa/wechatvibe/blob/main/bridge/backend_service.py) (Backend service), [`chatui/app.js`](https://github.com/tswawa/wechatvibe/blob/main/chatui/app.js) (Chat UI), [`native-reader/wr/service.py`](https://github.com/tswawa/wechatvibe/blob/main/native-reader/wr/service.py) (Native reader service), [`bridge/analysis_server.ts`](https://github.com/tswawa/wechatvibe/blob/main/bridge/analysis_server.ts) (Analysis server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop experience"]
  node_chatui["Chat UI<br/>[app.js]"]
  node_api_server["Analysis server<br/>[analysis_server.ts]"]
  node_contracts["Shared contracts<br/>[contracts.ts]"]
end

subgraph group_service["Application service"]
  node_backend["Backend service<br/>[backend_service.py]"]
  node_history["History browser<br/>[history_browser.py]"]
  node_selection["Conversation selection"]
  node_batch["Message batches<br/>[batch_engine.py]"]
end

subgraph group_reader["WeChat reader"]
  node_wechat_source["WeChat source<br/>[wechat_source.py]"]
  node_native_service["Native reader service<br/>[service.py]"]
  node_discovery["Account discovery<br/>[discovery.py]"]
  node_database["Message database<br/>[database.py]"]
end

subgraph group_analysis["Analysis engines"]
  node_laya["Local Laya analysis<br/>[analysis.ts]"]
  node_laya_agent["Laya agent<br/>[agent.ts]"]
  node_tokenizer["Laya tokenizer<br/>[tokenizer.ts]"]
  node_api_message["API message analysis"]
  node_model_connectors["Model connectors"]
  node_api_portrait["API portrait analysis<br/>[api-portrait.ts]"]
end

subgraph group_state["Results and profiles"]
  node_result_store[("Analysis storage<br/>[result_store.py]")]
  node_portrait_statistics["Portrait statistics"]
  node_profile_signals["Profile signals<br/>[profile_signals.py]"]
end

node_user(("User"))

node_user -->|"selects chats"| node_chatui
node_chatui -.->|"requests analysis"| node_api_server
node_api_server -.->|"dispatches requests"| node_backend
node_backend -->|"reads messages"| node_wechat_source
node_backend -->|"uses history"| node_history
node_backend -->|"manages selection"| node_selection
node_wechat_source -->|"reads WeChat"| node_native_service
node_native_service -->|"discovers accounts"| node_discovery
node_native_service -->|"queries shards"| node_database
node_backend -->|"processes batches"| node_batch
node_batch -.->|"persists outcomes"| node_result_store
node_backend -->|"stores results"| node_result_store
node_backend -.->|"requests local analysis"| node_laya
node_backend -.->|"requests API analysis"| node_api_message
node_laya -->|"runs inference"| node_laya_agent
node_laya_agent -->|"tokenizes input"| node_tokenizer
node_api_message -->|"sends model requests"| node_model_connectors
node_backend -.->|"requests portrait analysis"| node_api_portrait
node_api_portrait -->|"uses model API"| node_model_connectors
node_backend -.->|"computes portrait totals"| node_portrait_statistics
node_backend -->|"uses profile signals"| node_profile_signals
node_chatui -.->|"validates shared data"| node_contracts

click node_chatui "https://github.com/tswawa/wechatvibe/blob/main/chatui/app.js"
click node_api_server "https://github.com/tswawa/wechatvibe/blob/main/bridge/analysis_server.ts"
click node_backend "https://github.com/tswawa/wechatvibe/blob/main/bridge/backend_service.py"
click node_history "https://github.com/tswawa/wechatvibe/blob/main/bridge/history_browser.py"
click node_selection "https://github.com/tswawa/wechatvibe/blob/main/bridge/conversation_selection.py"
click node_wechat_source "https://github.com/tswawa/wechatvibe/blob/main/bridge/wechat_source.py"
click node_native_service "https://github.com/tswawa/wechatvibe/blob/main/native-reader/wr/service.py"
click node_discovery "https://github.com/tswawa/wechatvibe/blob/main/native-reader/wr/discovery.py"
click node_database "https://github.com/tswawa/wechatvibe/blob/main/native-reader/wr/database.py"
click node_batch "https://github.com/tswawa/wechatvibe/blob/main/bridge/batch_engine.py"
click node_result_store "https://github.com/tswawa/wechatvibe/blob/main/bridge/result_store.py"
click node_laya "https://github.com/tswawa/wechatvibe/blob/main/electron/analysis.ts"
click node_laya_agent "https://github.com/tswawa/wechatvibe/blob/main/electron/laya/agent.ts"
click node_tokenizer "https://github.com/tswawa/wechatvibe/blob/main/electron/laya/tokenizer.ts"
click node_api_message "https://github.com/tswawa/wechatvibe/blob/main/electron/api-message-insights.ts"
click node_model_connectors "https://github.com/tswawa/wechatvibe/blob/main/electron/model-connectors.ts"
click node_api_portrait "https://github.com/tswawa/wechatvibe/blob/main/electron/api-portrait.ts"
click node_portrait_statistics "https://github.com/tswawa/wechatvibe/blob/main/bridge/api_portrait_statistics.py"
click node_profile_signals "https://github.com/tswawa/wechatvibe/blob/main/bridge/profile_signals.py"
click node_contracts "https://github.com/tswawa/wechatvibe/blob/main/shared/contracts.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_chatui,node_api_server,node_contracts,node_user toneBlue
class node_backend,node_history,node_selection,node_batch toneAmber
class node_wechat_source,node_native_service,node_discovery,node_database toneMint
class node_laya,node_laya_agent,node_tokenizer,node_api_message,node_model_connectors,node_api_portrait toneRose
class node_result_store,node_portrait_statistics,node_profile_signals toneIndigo
```

## Components

### Desktop experience

- [Chat UI](https://github.com/tswawa/wechatvibe/blob/main/chatui/app.js): `chatui/app.js`
- [Analysis server](https://github.com/tswawa/wechatvibe/blob/main/bridge/analysis_server.ts): `bridge/analysis_server.ts`
- [Shared contracts](https://github.com/tswawa/wechatvibe/blob/main/shared/contracts.ts): `shared/contracts.ts`

### Application service

- [Backend service](https://github.com/tswawa/wechatvibe/blob/main/bridge/backend_service.py): `bridge/backend_service.py`
- [History browser](https://github.com/tswawa/wechatvibe/blob/main/bridge/history_browser.py): `bridge/history_browser.py`
- [Conversation selection](https://github.com/tswawa/wechatvibe/blob/main/bridge/conversation_selection.py): `bridge/conversation_selection.py`
- [Message batches](https://github.com/tswawa/wechatvibe/blob/main/bridge/batch_engine.py): `bridge/batch_engine.py`

### WeChat reader

- [WeChat source](https://github.com/tswawa/wechatvibe/blob/main/bridge/wechat_source.py): `bridge/wechat_source.py`
- [Native reader service](https://github.com/tswawa/wechatvibe/blob/main/native-reader/wr/service.py): `native-reader/wr/service.py`
- [Account discovery](https://github.com/tswawa/wechatvibe/blob/main/native-reader/wr/discovery.py): `native-reader/wr/discovery.py`
- [Message database](https://github.com/tswawa/wechatvibe/blob/main/native-reader/wr/database.py): `native-reader/wr/database.py`

### Analysis engines

- [Local Laya analysis](https://github.com/tswawa/wechatvibe/blob/main/electron/analysis.ts): `electron/analysis.ts`
- [Laya agent](https://github.com/tswawa/wechatvibe/blob/main/electron/laya/agent.ts): `electron/laya/agent.ts`
- [Laya tokenizer](https://github.com/tswawa/wechatvibe/blob/main/electron/laya/tokenizer.ts): `electron/laya/tokenizer.ts`
- [API message analysis](https://github.com/tswawa/wechatvibe/blob/main/electron/api-message-insights.ts): `electron/api-message-insights.ts`
- [Model connectors](https://github.com/tswawa/wechatvibe/blob/main/electron/model-connectors.ts): `electron/model-connectors.ts`
- [API portrait analysis](https://github.com/tswawa/wechatvibe/blob/main/electron/api-portrait.ts): `electron/api-portrait.ts`

### Results and profiles

- [Analysis storage](https://github.com/tswawa/wechatvibe/blob/main/bridge/result_store.py): `bridge/result_store.py`
- [Portrait statistics](https://github.com/tswawa/wechatvibe/blob/main/bridge/api_portrait_statistics.py): `bridge/api_portrait_statistics.py`
- [Profile signals](https://github.com/tswawa/wechatvibe/blob/main/bridge/profile_signals.py): `bridge/profile_signals.py`

### Other components

- **User**

## Connections

- User → Chat UI: selects chats (evidence: `README.md`)
- Chat UI → Analysis server: requests analysis
- Analysis server → Backend service: dispatches requests
- Backend service → WeChat source: reads messages (evidence: `bridge/backend_service.py`)
- Backend service → History browser: uses history (evidence: `bridge/backend_service.py`)
- Backend service → Conversation selection: manages selection (evidence: `bridge/backend_service.py`)
- WeChat source → Native reader service: reads WeChat (evidence: `bridge/wechat_source.py`)
- Native reader service → Account discovery: discovers accounts (evidence: `native-reader/wr/service.py`)
- Native reader service → Message database: queries shards (evidence: `native-reader/wr/service.py`)
- Backend service → Message batches: processes batches (evidence: `bridge/backend_service.py`)
- Message batches → Analysis storage: persists outcomes
- Backend service → Analysis storage: stores results (evidence: `bridge/backend_service.py`)
- Backend service → Local Laya analysis: requests local analysis
- Backend service → API message analysis: requests API analysis
- Local Laya analysis → Laya agent: runs inference (evidence: `electron/analysis.ts`)
- Laya agent → Laya tokenizer: tokenizes input (evidence: `electron/laya/agent.ts`)
- API message analysis → Model connectors: sends model requests (evidence: `electron/api-message-insights.ts`)
- Backend service → API portrait analysis: requests portrait analysis
- API portrait analysis → Model connectors: uses model API
- Backend service → Portrait statistics: computes portrait totals (evidence: `bridge/backend_service.py`)
- Backend service → Profile signals: uses profile signals (evidence: `bridge/backend_service.py`)
- Chat UI → Shared contracts: validates shared data
