# iszhouhua/social-media-copilot architecture

> Architecture diagram of the GitHub repository iszhouhua/social-media-copilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iszhouhua/social-media-copilot
- Repository: https://github.com/iszhouhua/social-media-copilot

## Overview

##### Project type and purpose
- This is a browser-extension (Chrome MV3) plugin written in TypeScript + React (WXT framework) that automates data collection from social-media platforms (小红书 XHS, 抖音 DY, 快手 KS).
- It provides a popup UI for user interactions, background scripts for orchestration and cross-origin data fetching, and content scripts injected into each platform’s web pages to parse and process platform data.

##### File structure
- Top-level directories:
- src/entrypoints – extension entry points:
– background/ – background script
– popup/ – extension popup UI (React+HTML)
– xhs.content/, dy.content/, ks.content/ – content scripts and platform-specific API/task modules
- src/components – shared React UI components
- src/utils – messaging, task orchestration, fileinfo, tailwind helpers
- docs/ – markdown docs and screenshots
- Key config files:
- wxt.config.ts – WXT build config for MV3 packaging
- web-ext.config.ts – additional extension build settings
- postcss.config.js, tailwind.config.js – styling
- tsconfig.json – TypeScript settings

##### README for additional insights
- Confirms use of WXT framework
- Lists features per platform (download media, crawl posts/comments/authors)
- Describes workflow: install extension → connect to server → invoke server-side APIs that proxy through plugin → receive data

##### Main components to illustrate
a. Browser environment
– Chrome host runs the extension (MV3)
b. Extension components
– Background Service Worker
- Orchestrates messages, holds persistent socket.io or WebSocket client for server connections (in server-mode)
- Receives commands from popup and forwards to content scripts
- Executes cross-origin fetch requests when needed
– Popup UI (React)
- Renders form fields, buttons, progress indicators using src/components
- Sends messages to background to begin crawling tasks
– Content Scripts (per platform)
- Injected into social media pages (xhs.content, dy.content, ks.content)
- Each has:
– api/ modules (request wrappers, typings)
– tasks/ modules (author, post, comment, mix-post processors & UI entrypoints)
– utils/ for media URL extraction, parsing
- Communicates with background via chrome.runtime messaging
c. Shared modules
– src/components – UI primitives, forms, dialogs (Tailwind + React)
– src/utils – messaging.ts, task.ts, fileinfo.ts, tw.ts
d. Static assets & localization

##### Relationships and data flows
1) User clicks button in Popup UI →
2) popup → background (chrome.runtime.sendMessage) →
3) background → content script (chrome.tabs.sendMessage) →
4) content script invokes platform’s API via fetch or via background on its behalf →
5) content script processes JSON/data, extracts media URLs, comment lists, author info →
6) content script → background (results) →
7) background → popup (update UI / download links)
- In server-mode (not open source branch), add socket.io channel:
background ↔ server (websocket)

##### Architectural patterns & design principles
- MV*(ish):
- UI layer (Popup)
- Orchestration layer (Background Worker)
- Platform logic layer (Content Scripts)
- Separation of concerns: platform-specific code isolated under each entrypoint
- Reusable React components under src/components
- Messaging bus via chrome.runtime for loose coupling
- Tailwind CSS + WXT for extensible, themable UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Host Layer
    subgraph "Browser Extension Host"
        direction TB
        subgraph "Popup UI (React)" 
            direction TB
            PopupHTML["index.html"]:::frontend
            PopupMain["main.tsx"]:::frontend
            PopupItem["item.tsx"]:::frontend
        end
        subgraph "Background Service Worker (TS, WXT)"
            bg["index.ts"]:::orchestration
        end
        subgraph "Content Scripts (Platform Logic)"
            direction TB
            subgraph "XHS Content Script"
                xhsEntry["index.tsx"]:::platform
                xhsApi["api/"]:::platform
                xhsTasks["tasks/"]:::platform
                xhsUtils["utils/"]:::platform
            end
            subgraph "Douyin (DY) Content Script"
                dyEntry["index.tsx"]:::platform
                dyApi["api/"]:::platform
                dyTasks["tasks/"]:::platform
                dyUtils["utils/"]:::platform
            end
            subgraph "Kuaishou (KS) Content Script"
                ksEntry["index.tsx"]:::platform
                ksApi["api/"]:::platform
                ksTasks["tasks/"]:::platform
                ksUtils["utils/"]:::platform
            end
        end
    end

    %% Shared Modules
    subgraph "Shared Modules"
        direction TB
        components["src/components"]:::shared
        utilsMsg["messaging.ts"]:::shared
        utilsTask["task.ts"]:::shared
        utilsFile["fileinfo.ts"]:::shared
        utilsTw["tw.ts"]:::shared
    end

    %% Static Assets & Localization
    subgraph "Static Assets & Localization"
        direction TB
        assetsIcons["src/assets/icons"]:::shared
        assetsCSS["tailwind.css"]:::shared
        locale["_locales"]:::shared
    end

    %% External Server
    server["External Server (WebSocket)"]:::external

    %% Message Flows
    PopupMain -->|"chrome.runtime.sendMessage"| bg
    bg -->|"chrome.tabs.sendMessage"| xhsEntry
    xhsEntry -->|"chrome.runtime.sendMessage (result)"| bg
    bg -->|"chrome.runtime.sendMessage (update)"| PopupMain

    bg <-->|"WebSocket (socket.io)"| server

    %% Click Events
    click PopupHTML "https://github.com/iszhouhua/social-media-copilot/blob/main/src/entrypoints/popup/index.html"
    click PopupMain "https://github.com/iszhouhua/social-media-copilot/blob/main/src/entrypoints/popup/main.tsx"
    click PopupItem "https://github.com/iszhouhua/social-media-copilot/blob/main/src/entrypoints/popup/item.tsx"
    click bg "https://github.com/iszhouhua/social-media-copilot/blob/main/src/entrypoints/background/index.ts"
    click xhsEntry "https://github.com/iszhouhua/social-media-copilot/blob/main/src/entrypoints/xhs.content/index.tsx"
    click xhsApi "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/xhs.content/api"
    click xhsTasks "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/xhs.content/tasks"
    click xhsUtils "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/xhs.content/utils"
    click dyEntry "https://github.com/iszhouhua/social-media-copilot/blob/main/src/entrypoints/dy.content/index.tsx"
    click dyApi "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/dy.content/api"
    click dyTasks "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/dy.content/tasks"
    click dyUtils "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/dy.content/utils"
    click ksEntry "https://github.com/iszhouhua/social-media-copilot/blob/main/src/entrypoints/ks.content/index.tsx"
    click ksApi "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/ks.content/api"
    click ksTasks "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/ks.content/tasks"
    click ksUtils "https://github.com/iszhouhua/social-media-copilot/tree/main/src/entrypoints/ks.content/utils"
    click components "https://github.com/iszhouhua/social-media-copilot/tree/main/src/components"
    click utilsMsg "https://github.com/iszhouhua/social-media-copilot/blob/main/src/utils/messaging.ts"
    click utilsTask "https://github.com/iszhouhua/social-media-copilot/blob/main/src/utils/task.ts"
    click utilsFile "https://github.com/iszhouhua/social-media-copilot/blob/main/src/utils/fileinfo.ts"
    click utilsTw "https://github.com/iszhouhua/social-media-copilot/blob/main/src/utils/tw.ts"
    click assetsIcons "https://github.com/iszhouhua/social-media-copilot/tree/main/src/assets/icons"
    click assetsCSS "https://github.com/iszhouhua/social-media-copilot/blob/main/src/assets/tailwind.css"
    click locale "https://github.com/iszhouhua/social-media-copilot/blob/main/src/public/_locales/zh_CN/messages.json"
    click WXT "https://github.com/iszhouhua/social-media-copilot/blob/main/wxt.config.ts"
    click WebExt "https://github.com/iszhouhua/social-media-copilot/blob/main/web-ext.config.ts"
    click tailwind "https://github.com/iszhouhua/social-media-copilot/blob/main/tailwind.config.js"
    click postcss "https://github.com/iszhouhua/social-media-copilot/blob/main/postcss.config.js"
    click tsconfig "https://github.com/iszhouhua/social-media-copilot/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#1E70BF,color:#000
    classDef orchestration fill:#E0F8E0,stroke:#2E8B57,color:#000
    classDef platform fill:#FFE8C0,stroke:#DE6B1D,color:#000
    classDef shared fill:#F5E0FF,stroke:#8A2BE2,color:#000
    classDef external fill:#F0F0F0,stroke:#909090,color:#000
```
