# astronaut-free/social-media-collector architecture

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

- Interactive diagram: https://gitdiagram.com/astronaut-free/social-media-collector
- Repository: https://github.com/astronaut-free/social-media-collector
- Video tour (about a minute): https://gitdiagram.com/astronaut-free/social-media-collector/video

## Overview

Social Media Collector accepts CLI requests to collect metadata, download media, or list creator content across Douyin, Xiaohongshu, and Bilibili. Its Watchdog checks local or Feishu monitor lists, discovers new items, optionally collects full metadata, deduplicates by stable identity, and writes results and monitor updates. Feishu is optional; OpenCLI supports browser-session-dependent access. The graph reflects README capabilities where source excerpts were incomplete; links for unsampled implementations are limited to documented behavior.

Main entry points: [`social_collector/router.py`](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/router.py) (Platform router), [`social_collector/cli.py`](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/cli.py) (Command router), [`social_collector/watchdog.py`](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/watchdog.py) (Monitor runner), [`social_collector/collectors/xiaohongshu.py`](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/collectors/xiaohongshu.py) (Xiaohongshu collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI interface"]
  node_cli["Command router<br/>[cli.py]"]
  node_doctor["Runtime checks<br/>[doctor.py]"]
end

subgraph group_collection["Collection"]
  node_router["Platform router<br/>[router.py]"]
  node_models["Content models<br/>[models.py]"]
  node_douyin["Douyin collector<br/>[douyin.py]"]
  node_xhs["Xiaohongshu collector<br/>[xiaohongshu.py]"]
  node_bilibili["Bilibili collector<br/>[bilibili.py]"]
end

subgraph group_monitoring["Watchdog"]
  node_watchdog["Monitor runner<br/>[watchdog.py]"]
  node_watchstore["Local watch state<br/>[watchdog.py]"]
end

subgraph group_integrations["Integrations"]
  node_opencli["OpenCLI<br/>[opencli.py]"]
  node_feishu_integration["Feishu adapter<br/>[feishu.py]"]
  node_feishu_schema["Table schema<br/>[feishu_schema.py]"]
end

node_operator(("User"))
node_media["Platform services"]
node_feishu_api[("Feishu Bitable")]

node_operator -->|"invokes"| node_cli
node_cli -->|"selects platform"| node_router
node_cli -->|"checks runtime"| node_doctor
node_cli -->|"runs monitoring"| node_watchdog
node_router -->|"selects collector"| node_douyin
node_router -->|"selects collector"| node_xhs
node_router -->|"selects collector"| node_bilibili
node_douyin -->|"requests metadata/media"| node_media
node_xhs -->|"requests content"| node_media
node_bilibili -->|"requests metadata/media"| node_media
node_xhs -.->|"runs browser commands"| node_opencli
node_watchdog -->|"creates collectors"| node_router
node_watchdog -->|"reads/writes state"| node_watchstore
node_watchdog -.->|"syncs monitors/results"| node_feishu_integration
node_feishu_integration -->|"uses field definitions"| node_feishu_schema
node_feishu_integration -.->|"reads/writes tables"| node_feishu_api

click node_cli "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/cli.py"
click node_doctor "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/doctor.py"
click node_router "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/router.py"
click node_models "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/models.py"
click node_douyin "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/collectors/douyin.py"
click node_xhs "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/collectors/xiaohongshu.py"
click node_bilibili "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/collectors/bilibili.py"
click node_opencli "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/opencli.py"
click node_watchdog "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/watchdog.py"
click node_watchstore "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/watchdog.py"
click node_feishu_integration "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/feishu.py"
click node_feishu_schema "https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/feishu_schema.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_cli,node_doctor,node_operator toneBlue
class node_router,node_models,node_douyin,node_xhs,node_bilibili,node_feishu_api toneAmber
class node_watchdog,node_watchstore toneMint
class node_opencli,node_feishu_integration,node_feishu_schema toneRose
class node_media toneIndigo
```

## Components

### CLI interface

- [Command router](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/cli.py): `social_collector/cli.py`
- [Runtime checks](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/doctor.py): `social_collector/doctor.py`

### Collection

- [Platform router](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/router.py): `social_collector/router.py`
- [Content models](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/models.py): `social_collector/models.py`
- [Douyin collector](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/collectors/douyin.py): `social_collector/collectors/douyin.py`
- [Xiaohongshu collector](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/collectors/xiaohongshu.py): `social_collector/collectors/xiaohongshu.py`
- [Bilibili collector](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/collectors/bilibili.py): `social_collector/collectors/bilibili.py`

### Watchdog

- [Monitor runner](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/watchdog.py): `social_collector/watchdog.py`
- [Local watch state](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/watchdog.py): `social_collector/watchdog.py`

### Integrations

- [OpenCLI](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/opencli.py): `social_collector/opencli.py`
- [Feishu adapter](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/feishu.py): `social_collector/feishu.py`
- [Table schema](https://github.com/astronaut-free/social-media-collector/blob/main/social_collector/feishu_schema.py): `social_collector/feishu_schema.py`

### Other components

- **User**
- **Platform services**
- **Feishu Bitable**

## Connections

- User → Command router: invokes
- Command router → Platform router: selects platform
- Command router → Runtime checks: checks runtime
- Command router → Monitor runner: runs monitoring
- Platform router → Douyin collector: selects collector
- Platform router → Xiaohongshu collector: selects collector
- Platform router → Bilibili collector: selects collector
- Douyin collector → Platform services: requests metadata/media
- Xiaohongshu collector → Platform services: requests content
- Bilibili collector → Platform services: requests metadata/media
- Xiaohongshu collector → OpenCLI: runs browser commands
- Monitor runner → Platform router: creates collectors
- Monitor runner → Local watch state: reads/writes state
- Monitor runner → Feishu adapter: syncs monitors/results
- Feishu adapter → Table schema: uses field definitions
- Feishu adapter → Feishu Bitable: reads/writes tables