# dreammis/social-auto-upload architecture

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

- Interactive diagram: https://gitdiagram.com/dreammis/social-auto-upload
- Repository: https://github.com/dreammis/social-auto-upload

## Overview

Based on our analysis of the file tree and README, this project is a Python‐based automated video uploader that targets multiple social media platforms. Its purpose is to prepare videos (along with meta information), manage login and cookie retrieval, and handle the upload process for platforms such as douyin, tencent (视频号), bilibili, xhs (小红书), tiktok, and fast platforms like kuaishou. The project offers both CLI usage and example scripts that users can integrate into their own workflows.

##### Main Components
- CLI Interface: Represented by cli_main.py which acts as the entry point. It accepts the platform, account name, and action (upload, login, watch) parameters.
- Configuration Module: Includes conf.py and parts of utility modules (like utils/constant.py) that provide settings such as LOCAL_CHROME_PATH.
- Uploader Modules: There is a dedicated uploader folder with subdirectories for each platform (e.g., bilibili_uploader, douyin_uploader, ks_uploader, tencent_uploader, tk_uploader, xhs_uploader). Each module contains its main.py and additional scripts for handling login (cookie retrieval) and video upload.
- Examples: The examples directory contains sample scripts that demonstrate how to get cookies and upload videos. These scripts act as a practical guide for users or developers integrating the functionality.
- Utility Library: The utils folder provides shared functionality (e.g., basic functionality for social media operations, logging, file handling) that is used across different uploader modules.
- Video Management: The videos folder stores sample media files (video and text metadata). This represents the source content that is uploaded by the system.
- Media Resources: The media folder (and its subfolders) holds images and other static resources used in the README or potentially in the user interface (show illustrations, GIFs).

##### Relationships and Interactions
- The CLI (cli_main.py) is the controller that parses user input and routes commands to the appropriate module.
- Each uploader module internally uses browser automation (via playwright) to simulate the upload process and even to get cookies.
- Configuration settings from conf.py and parameter files (like tk_config.py for tiktok) are used to ensure compatibility (e.g., using a local chrome executable) and manage scheduling (e.g., cron or delayed uploads).
- The utility functions in the utils folder provide cross-cutting services such as logging and file operations, which support operations in different uploader modules.
- The examples directory is used to demonstrate how the modules can be used directly outside of a larger integrated system.

##### Important Architectural Patterns and Technologies
- Modular Design: Uploader modules are separated by platform, which simplifies adding or updating a specific social-media integration.
- Separation of Concerns: Distinct directories handle CLI, configuration, uploader logic, utility functions, and examples. This makes the codebase easier to maintain.
- External Dependencies: The use of playwright (for browser automation) and external binaries (e.g., biliup.exe for bilibili) are key technological choices.
- Scheduling and Automation: The project supports scheduled uploads (utilizing cron-like timing) and manual immediate uploads.
- Extensibility: The system is designed so that users can easily integrate additional uploaders or extend functionality using the provided examples and utility libraries.

##### Specific Elements
- User inputs (platform, account, action) flowing from CLI to the corresponding uploader module.
- Data flow between configuration files and uploader modules.
- Command-line components versus background modules.
- Platform-specific logic versus shared utilities.
- Notes for key processes like "Cookie Retrieval", "Video Upload", and "Scheduled Release".

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level Components
    CLI["CLI Interface (cli_main.py)"]:::cli

    %% Configuration Modules
    subgraph "Configuration & Settings"
        config_global["Global Config (conf.py)"]:::config
        config_tk["TikTok Config (tk_config.py)"]:::config
    end

    %% Uploader Modules
    subgraph "Uploader Modules"
        douyin["Douyin Uploader"]:::uploader
        bilibili["Bilibili Uploader"]:::uploader
        kuaishou["Kuaishou Uploader"]:::uploader
        tencent["Tencent Uploader"]:::uploader
        subgraph "TikTok Uploader"
            tiktok_main["TikTok Uploader - Main"]:::uploader
            tiktok_chrome["TikTok Uploader - Chrome"]:::uploader
        end
        subgraph "XHS Uploader"
            xhs_main["XHS Uploader - Main"]:::uploader
            xhs_qr["XHS Login QR"]:::uploader
        end
        biliup["Biliup Tool"]:::external
    end

    %% Supporting and External Components
    utils["Utility Functions (utils)"]:::utility
    examples["Examples & Demo Scripts (examples/)"]:::examples
    videos["Video Content (videos)"]:::video
    media["Media Resources (media)"]:::media
    playwright["Browser Automation (playwright)"]:::external

    %% Arrows: CLI interactions
    CLI -->|"parses|command"| douyin
    CLI -->|"parses|command"| bilibili
    CLI -->|"parses|command"| kuaishou
    CLI -->|"parses|command"| tencent
    CLI -->|"parses|command"| tiktok_main
    CLI -->|"parses|command"| xhs_main

    %% Arrows: Configuration providing settings
    config_global ---|"supplies_Settings"| douyin
    config_global ---|"supplies_Settings"| bilibili
    config_global ---|"supplies_Settings"| kuaishou
    config_global ---|"supplies_Settings"| tencent
    config_global ---|"supplies_Settings"| tiktok_main
    config_global ---|"supplies_Settings"| tiktok_chrome
    config_global ---|"supplies_Settings"| xhs_main
    config_global ---|"supplies_Settings"| xhs_qr

    config_tk ---|"supplies_Settings"| tiktok_main
    config_tk ---|"supplies_Settings"| tiktok_chrome

    %% Arrows: Utility functions support
    utils ---|"supports"| douyin
    utils ---|"supports"| bilibili
    utils ---|"supports"| kuaishou
    utils ---|"supports"| tencent
    utils ---|"supports"| tiktok_main
    utils ---|"supports"| tiktok_chrome
    utils ---|"supports"| xhs_main
    utils ---|"supports"| xhs_qr

    %% Arrows: Video and Media Content provided to uploaders
    videos ---|"provides_media"| douyin
    videos ---|"provides_media"| bilibili
    videos ---|"provides_media"| kuaishou
    videos ---|"provides_media"| tencent
    videos ---|"provides_media"| tiktok_main
    videos ---|"provides_media"| tiktok_chrome
    videos ---|"provides_media"| xhs_main
    videos ---|"provides_media"| xhs_qr

    media ---|"supplements"| douyin
    media ---|"supplements"| bilibili
    media ---|"supplements"| kuaishou
    media ---|"supplements"| tencent
    media ---|"supplements"| tiktok_main
    media ---|"supplements"| tiktok_chrome
    media ---|"supplements"| xhs_main
    media ---|"supplements"| xhs_qr

    %% Arrows: Uploader modules using external browser automation
    douyin -->|"automates_browser"| playwright
    bilibili -->|"automates_browser"| playwright
    kuaishou -->|"automates_browser"| playwright
    tencent -->|"automates_browser"| playwright
    tiktok_main -->|"automates_browser"| playwright
    tiktok_chrome -->|"automates_browser"| playwright
    xhs_main -->|"automates_browser"| playwright
    xhs_qr -->|"automates_browser"| playwright

    %% Arrows: Internal dependency within Bilibili uploader
    bilibili -->|"invokes"| biliup

    %% Arrows: XHS login process
    xhs_main -->|"triggers"| xhs_qr

    %% Arrows: Examples demonstrating usage
    examples ---|"demonstrates_usage"| CLI

    %% Click Events
    click CLI "https://github.com/dreammis/social-auto-upload/blob/main/cli_main.py"
    click config_global "https://github.com/dreammis/social-auto-upload/blob/main/conf.py"
    click config_tk "https://github.com/dreammis/social-auto-upload/blob/main/uploader/tk_uploader/tk_config.py"
    click douyin "https://github.com/dreammis/social-auto-upload/blob/main/uploader/douyin_uploader/main.py"
    click bilibili "https://github.com/dreammis/social-auto-upload/blob/main/uploader/bilibili_uploader/main.py"
    click biliup "https://github.com/dreammis/social-auto-upload/blob/main/uploader/bilibili_uploader/biliup.exe"
    click kuaishou "https://github.com/dreammis/social-auto-upload/blob/main/uploader/ks_uploader/main.py"
    click tencent "https://github.com/dreammis/social-auto-upload/blob/main/uploader/tencent_uploader/main.py"
    click tiktok_main "https://github.com/dreammis/social-auto-upload/blob/main/uploader/tk_uploader/main.py"
    click tiktok_chrome "https://github.com/dreammis/social-auto-upload/blob/main/uploader/tk_uploader/main_chrome.py"
    click xhs_main "https://github.com/dreammis/social-auto-upload/blob/main/uploader/xhs_uploader/main.py"
    click xhs_qr "https://github.com/dreammis/social-auto-upload/blob/main/uploader/xhs_uploader/xhs_login_qrcode.py"
    click examples "https://github.com/dreammis/social-auto-upload/tree/main/examples/"
    click utils "https://github.com/dreammis/social-auto-upload/tree/main/utils/"
    click videos "https://github.com/dreammis/social-auto-upload/tree/main/videos/"
    click media "https://github.com/dreammis/social-auto-upload/tree/main/media/"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef config fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef uploader fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef utility fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef examples fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef video fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef media fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
