# freestylefly/wechatbridge architecture

> Architecture diagram of the GitHub repository freestylefly/wechatbridge, 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/freestylefly/wechatbridge
- Repository: https://github.com/freestylefly/wechatbridge

## Overview

WeChatBridge is a local-first WeChat share-extension app for forwarding exported chat archives to AI applications, Obsidian, folders, custom targets, or the clipboard. Main flow: a user shares a WeChat ZIP, the platform share entry stages files in the inbox, and the resident app discovers the batch and routes delivery; collection mode groups multiple shares before sending. Scenes and skills add destination-specific context, while history and settings support recovery and configuration. Windows counterparts are included. Relationships below are limited to those established by the README or shown in the supplied source index and excerpts.

Main entry points: [`macos/Sources/WeChatBridgeApp/ActionRunner.swift`](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/ActionRunner.swift) (macOS action runner), [`macos/Sources/WeChatBridgeApp/AppModel.swift`](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/AppModel.swift) (Resident app model), [`windows/src/WeChatBridge.Windows.Core/Delivery/DeliveryEngine.cs`](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Delivery/DeliveryEngine.cs) (Windows delivery engine), [`macos/Sources/WeChatBridgeShare/ShareViewController.swift`](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeShare/ShareViewController.swift) (macOS share entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_share["Share intake"]
  node_macshare["macOS share entry"]
  node_importer["Attachment importer"]
  node_inbox[("Inbox batch store<br/>[Inbox.swift]")]
  node_winshare["Windows share target<br/>[Program.cs]"]
  node_wincollection["Windows collection service"]
end

subgraph group_delivery["Delivery and archive"]
  node_runner["macOS action runner<br/>[ActionRunner.swift]"]
  node_winengine["Windows delivery engine<br/>[DeliveryEngine.cs]"]
  node_winobsidian["Windows Obsidian delivery"]
  node_winfolder["Windows folder delivery<br/>[FolderDelivery.cs]"]
end

subgraph group_context["Scenes and skills"]
  node_scene["Scene coordination"]
  node_skills[("Skill library<br/>[SkillLibrary.swift]")]
  node_sceneconfig[("Scene settings<br/>[Preferences.swift]")]
  node_winscene["Windows scene service<br/>[SceneService.cs]"]
  node_winskills["Windows skill service<br/>[SkillService.cs]"]
end

subgraph group_app["App and history"]
  node_appmodel["Resident app model<br/>[AppModel.swift]"]
  node_history[("Local history<br/>[InboxReader.swift]")]
  node_ui["App and settings UI<br/>[App.swift]"]
  node_winapp["Windows app view model<br/>[MainViewModel.cs]"]
end

node_wechat(("WeChat user"))
node_agent["AI agent apps"]
node_obsidian[("Obsidian vault")]
node_folder[("Chosen folder")]
node_clipboard["System clipboard"]
node_custom["Custom target app"]

node_wechat -->|"shares archive"| node_macshare
node_macshare -->|"imports attachments"| node_importer
node_macshare -->|"stages batch"| node_inbox
node_macshare -->|"launches app"| node_appmodel
node_appmodel -->|"reads batches"| node_inbox
node_appmodel -->|"tracks history"| node_history
node_ui -->|"presents state"| node_appmodel
node_appmodel -.->|"dispatches actions"| node_runner
node_runner -->|"pastes archive"| node_agent
node_runner -->|"creates notes"| node_obsidian
node_runner -->|"writes files"| node_folder
node_runner -->|"copies files"| node_clipboard
node_runner -->|"forwards archive"| node_custom
node_appmodel -.->|"uses scene"| node_scene
node_scene -.->|"reads settings"| node_sceneconfig
node_scene -.->|"resolves skills"| node_skills
node_wechat -->|"shares archive"| node_winshare
node_winshare -->|"stages collections"| node_wincollection
node_winapp -.->|"requests delivery"| node_winengine
node_winengine -.->|"delivers notes"| node_winobsidian
node_winengine -.->|"writes folder"| node_winfolder
node_winengine -.->|"fallback copy"| node_clipboard
node_winengine -->|"activates and pastes"| node_agent
node_winscene -.->|"renders skill context"| node_winskills

click node_macshare "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeShare/ShareViewController.swift"
click node_importer "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeShare/AttachmentImporter.swift"
click node_inbox "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeCore/Inbox.swift"
click node_winshare "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.ShareTarget/Program.cs"
click node_wincollection "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Collections/CollectionService.cs"
click node_appmodel "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/AppModel.swift"
click node_history "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeCore/InboxReader.swift"
click node_ui "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/App.swift"
click node_winapp "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows/MainViewModel.cs"
click node_runner "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/ActionRunner.swift"
click node_winengine "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Delivery/DeliveryEngine.cs"
click node_scene "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/WeChat/SceneCoordinator.swift"
click node_skills "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/SkillLibrary.swift"
click node_sceneconfig "https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/Preferences.swift"
click node_winscene "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows/Services/SceneService.cs"
click node_winskills "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows/Services/SkillService.cs"
click node_winobsidian "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Obsidian/KnowledgeDelivery.cs"
click node_winfolder "https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Obsidian/FolderDelivery.cs"

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_macshare,node_importer,node_inbox,node_winshare,node_wincollection,node_wechat toneBlue
class node_runner,node_winengine,node_winobsidian,node_winfolder,node_obsidian,node_folder toneAmber
class node_scene,node_skills,node_sceneconfig,node_winscene,node_winskills toneMint
class node_appmodel,node_history,node_ui,node_winapp toneRose
class node_agent,node_clipboard,node_custom toneIndigo
```

## Components

### Share intake

- [macOS share entry](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeShare/ShareViewController.swift): `macos/Sources/WeChatBridgeShare/ShareViewController.swift`
- [Attachment importer](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeShare/AttachmentImporter.swift): `macos/Sources/WeChatBridgeShare/AttachmentImporter.swift`
- [Inbox batch store](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeCore/Inbox.swift): `macos/Sources/WeChatBridgeCore/Inbox.swift`
- [Windows share target](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.ShareTarget/Program.cs): `windows/src/WeChatBridge.ShareTarget/Program.cs`
- [Windows collection service](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Collections/CollectionService.cs): `windows/src/WeChatBridge.Windows.Core/Collections/CollectionService.cs`

### Delivery and archive

- [macOS action runner](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/ActionRunner.swift): `macos/Sources/WeChatBridgeApp/ActionRunner.swift`
- [Windows delivery engine](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Delivery/DeliveryEngine.cs): `windows/src/WeChatBridge.Windows.Core/Delivery/DeliveryEngine.cs`
- [Windows Obsidian delivery](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Obsidian/KnowledgeDelivery.cs): `windows/src/WeChatBridge.Windows.Core/Obsidian/KnowledgeDelivery.cs`
- [Windows folder delivery](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows.Core/Obsidian/FolderDelivery.cs): `windows/src/WeChatBridge.Windows.Core/Obsidian/FolderDelivery.cs`

### Scenes and skills

- [Scene coordination](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/WeChat/SceneCoordinator.swift): `macos/Sources/WeChatBridgeApp/WeChat/SceneCoordinator.swift`
- [Skill library](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/SkillLibrary.swift): `macos/Sources/WeChatBridgeApp/SkillLibrary.swift`
- [Scene settings](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/Preferences.swift): `macos/Sources/WeChatBridgeApp/Preferences.swift`
- [Windows scene service](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows/Services/SceneService.cs): `windows/src/WeChatBridge.Windows/Services/SceneService.cs`
- [Windows skill service](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows/Services/SkillService.cs): `windows/src/WeChatBridge.Windows/Services/SkillService.cs`

### App and history

- [Resident app model](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/AppModel.swift): `macos/Sources/WeChatBridgeApp/AppModel.swift`
- [Local history](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeCore/InboxReader.swift): `macos/Sources/WeChatBridgeCore/InboxReader.swift`
- [App and settings UI](https://github.com/freestylefly/wechatbridge/blob/main/macos/Sources/WeChatBridgeApp/App.swift): `macos/Sources/WeChatBridgeApp/App.swift`
- [Windows app view model](https://github.com/freestylefly/wechatbridge/blob/main/windows/src/WeChatBridge.Windows/MainViewModel.cs): `windows/src/WeChatBridge.Windows/MainViewModel.cs`

### Other components

- **WeChat user**
- **AI agent apps**
- **Obsidian vault**
- **Chosen folder**
- **System clipboard**
- **Custom target app**

## Connections

- WeChat user → macOS share entry: shares archive (evidence: `README.md`)
- macOS share entry → Attachment importer: imports attachments (evidence: `macos/Sources/WeChatBridgeShare/ShareViewController.swift`)
- macOS share entry → Inbox batch store: stages batch (evidence: `macos/Sources/WeChatBridgeShare/ShareViewController.swift`)
- macOS share entry → Resident app model: launches app (evidence: `macos/Sources/WeChatBridgeShare/ShareViewController.swift`)
- Resident app model → Inbox batch store: reads batches (evidence: `macos/Sources/WeChatBridgeApp/AppModel.swift`)
- Resident app model → Local history: tracks history (evidence: `macos/Sources/WeChatBridgeApp/AppModel.swift`)
- App and settings UI → Resident app model: presents state (evidence: `macos/Sources/WeChatBridgeApp/App.swift`)
- Resident app model → macOS action runner: dispatches actions (evidence: `macos/Sources/WeChatBridgeApp/ActionRunner.swift`)
- macOS action runner → AI agent apps: pastes archive (evidence: `README.md`)
- macOS action runner → Obsidian vault: creates notes (evidence: `README.md`)
- macOS action runner → Chosen folder: writes files (evidence: `README.md`)
- macOS action runner → System clipboard: copies files (evidence: `README.md`)
- macOS action runner → Custom target app: forwards archive (evidence: `README.md`)
- Resident app model → Scene coordination: uses scene
- Scene coordination → Scene settings: reads settings
- Scene coordination → Skill library: resolves skills
- WeChat user → Windows share target: shares archive (evidence: `README.md`)
- Windows share target → Windows collection service: stages collections (evidence: `windows/src/WeChatBridge.ShareTarget/Program.cs`)
- Windows app view model → Windows delivery engine: requests delivery
- Windows delivery engine → Windows Obsidian delivery: delivers notes
- Windows delivery engine → Windows folder delivery: writes folder
- Windows delivery engine → System clipboard: fallback copy
- Windows delivery engine → AI agent apps: activates and pastes (evidence: `windows/src/WeChatBridge.Windows.Core/Delivery/DeliveryEngine.cs`)
- Windows scene service → Windows skill service: renders skill context
