# joeanamier/xhs-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/joeanamier/xhs-downloader
- Repository: https://github.com/joeanamier/xhs-downloader

## Overview

##### Main Components
- Entry Points:
– main.py: Acts as one main entry point that branches into different modes (CLI/TUI modes, server/API mode, or command‐line mode).
– example.py: Contains examples for secondary development.
- User Interface Modules:
– CLI: Folder “source/CLI” which handles command-line operations.
– TUI: Folder “source/TUI” that manages the terminal-based UI experience with components for about, app, index, loading, monitor, progress, record, setting, and update.
- Core Business Logic:
– Application Layer (“source/application”): Modules such as app.py, download.py, explore.py, image.py, request.py, video.py provide the core functionalities like link extraction, content download and processing.
– Module Layer (“source/module”): Components including extend.py, manager.py, model.py, recorder.py, settings.py, static.py, tools.py provide supporting functions, state management, extensions, and configuration.
- Extensions & Additional Processing:
– Expansion (“source/expansion”): Contains browser interaction, cleanup, file conversion, error handling, namespace management, and file truncation – these modules add extra processing capabilities.
– Translation (“source/translation”): Offers localization/translation capabilities via translate.py.
- Resources & Assets:
– Locale: Contains localization files (MO/PO/POT files) for multiple languages.
- Infrastructure & Deployment:
– Dockerfile: Allows building the project as a containerized application.
– .github/workflows: Contains GitHub Actions workflows to build executable programs and Docker images.
– Requirements.txt: Lists external dependencies for the project.

##### Relationships and Data Flow
- The user interacts with the application in multiple ways:
– Through the terminal using CLI or TUI modes.
– By using browser scripts (e.g., Tampermonkey user script) to extract content and then piping them into the tool.
– In server mode (API), where HTTP POST requests (with JSON payload) are handled when “python main.py server” is run.
- The entry point (main.py) branches to the desired mode based on the command-line argument.
- UI modules (CLI/TUI) call functions from the Application layer to extract content information (e.g., content download URLs).
- The Application layer, in coordination with Modules and Expansions, handles file downloads, network requests, retries, and content integrity checks.
- The Translation layer along with locale resource files ensures that messages and UI text are rendered in the correct language.
- For Docker deployment, the Dockerfile and GitHub Actions workflows are used to automatically build, package, and deploy the application.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clear separation between UI (CLI/TUI), core business logic (Application), supporting modules (Module and Expansion), and infrastructure (API server, Docker container).
- Extensibility: The project is organized into submodules (module/extension) that allow for enhanced features such as file conversion, error handling, and localization.
- Configuration Driven: Uses external configuration (like settings.json) and locale files to manage runtime behavior and language support.
- CI/CD Integration: GitHub workflows in .github/workflows indicate a modern approach in automating builds and releases, including manual triggers for building executables and Docker images.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        EP_main["main.py (Entry)"]:::entry
        EP_example["example.py (Examples)"]:::entry
    end

    %% External Inputs
    subgraph "External Inputs"
        I_clipboard["Terminal/Clipboard"]:::external
        I_browser["Browser/Userscript"]:::external
        I_api["HTTP_API_Request"]:::external
    end

    %% User Interfaces
    subgraph "User Interfaces"
        UI_CLI["CLI Interface"]:::ui
        UI_TUI["TUI Interface"]:::ui
        UI_API["Server/API Mode"]:::ui
    end

    %% Core Business Logic
    subgraph "Core Business Logic"
        subgraph "Application Layer"
            AL_app["app.py"]:::business
            AL_download["download.py"]:::business
            AL_explore["explore.py"]:::business
            AL_image["image.py"]:::business
            AL_request["request.py"]:::business
            AL_video["video.py"]:::business
        end
        subgraph "Module Layer"
            ML_extend["extend.py"]:::module
            ML_manager["manager.py"]:::module
            ML_model["model.py"]:::module
            ML_recorder["recorder.py"]:::module
            ML_settings["settings.py"]:::module
            ML_static["static.py"]:::module
            ML_tools["tools.py"]:::module
        end
        subgraph "Expansion"
            EX_browser["browser.py"]:::expansion
            EX_cleaner["cleaner.py"]:::expansion
            EX_converter["converter.py"]:::expansion
            EX_error["error.py"]:::expansion
            EX_file_folder["file_folder.py"]:::expansion
            EX_namespace["namespace.py"]:::expansion
            EX_truncate["truncate.py"]:::expansion
        end
    end

    %% Localization
    subgraph "Localization"
        TR_translate["translate.py"]:::translation
        LC_locale["Locale Resources"]:::translation
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure"
        DEP_docker["Dockerfile (Docker)"]:::infra
        DEP_cicd["CI/CD Workflows"]:::infra
        DEP_dependencies["requirements.txt"]:::infra
        STATIC_assets["Static Assets"]:::infra
    end

    %% Connections from Entry Points to UI
    EP_main -->|"branch_to_mode"| UI_CLI
    EP_main -->|"branch_to_mode"| UI_TUI
    EP_main -->|"branch_to_mode"| UI_API

    %% External Inputs feeding into UI
    I_clipboard --> UI_CLI
    I_clipboard --> UI_TUI
    I_browser --> UI_TUI
    I_api --> UI_API

    %% UI calling Core Business Logic
    UI_CLI -->|"calls"| AL_app
    UI_TUI -->|"calls"| AL_app
    UI_API -->|"triggers"| AL_request

    %% Internal dependencies within Core Business Logic
    AL_app -->|"uses"| ML_manager
    AL_app -->|"uses"| ML_tools
    AL_download -->|"integrates"| EX_converter
    AL_explore -->|"integrates"| EX_browser

    %% Localization flow
    TR_translate --> LC_locale
    UI_TUI -->|"localizes"| TR_translate

    %% Infrastructure connections
    UI_TUI -->|"loads"| STATIC_assets
    AL_download -->|"requires"| DEP_dependencies
    DEP_docker --> DEP_cicd
    AL_request -->|"packaged_in"| DEP_docker
    EX_error -->|"reports_to"| ML_recorder
    DEP_cicd -->|"automates"| DEP_docker

    %% Secondary development example connection
    EP_example -->|"demonstrates"| EP_main

    %% Class Definitions
    classDef entry fill:#f6d186,stroke:#333,stroke-width:2px;
    classDef ui fill:#a2d2ff,stroke:#333,stroke-width:2px;
    classDef business fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef module fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef expansion fill:#ffd6a5,stroke:#333,stroke-width:2px;
    classDef translation fill:#ffb7b2,stroke:#333,stroke-width:2px;
    classDef infra fill:#c0d6e4,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px;

    %% Click Events
    click EP_main "https://github.com/joeanamier/xhs-downloader/blob/master/main.py"
    click EP_example "https://github.com/joeanamier/xhs-downloader/blob/master/example.py"
    click UI_CLI "https://github.com/joeanamier/xhs-downloader/tree/master/source/CLI"
    click UI_CLI "https://github.com/joeanamier/xhs-downloader/blob/master/source/CLI/main.py"
    click UI_TUI "https://github.com/joeanamier/xhs-downloader/tree/master/source/TUI"
    click AL_app "https://github.com/joeanamier/xhs-downloader/blob/master/source/application/app.py"
    click AL_download "https://github.com/joeanamier/xhs-downloader/blob/master/source/application/download.py"
    click AL_explore "https://github.com/joeanamier/xhs-downloader/blob/master/source/application/explore.py"
    click AL_image "https://github.com/joeanamier/xhs-downloader/blob/master/source/application/image.py"
    click AL_request "https://github.com/joeanamier/xhs-downloader/blob/master/source/application/request.py"
    click AL_video "https://github.com/joeanamier/xhs-downloader/blob/master/source/application/video.py"
    click ML_extend "https://github.com/joeanamier/xhs-downloader/blob/master/source/module/extend.py"
    click ML_manager "https://github.com/joeanamier/xhs-downloader/blob/master/source/module/manager.py"
    click ML_model "https://github.com/joeanamier/xhs-downloader/blob/master/source/module/model.py"
    click ML_recorder "https://github.com/joeanamier/xhs-downloader/blob/master/source/module/recorder.py"
    click ML_settings "https://github.com/joeanamier/xhs-downloader/blob/master/source/module/settings.py"
    click ML_static "https://github.com/joeanamier/xhs-downloader/blob/master/source/module/static.py"
    click ML_tools "https://github.com/joeanamier/xhs-downloader/blob/master/source/module/tools.py"
    click EX_browser "https://github.com/joeanamier/xhs-downloader/blob/master/source/expansion/browser.py"
    click EX_cleaner "https://github.com/joeanamier/xhs-downloader/blob/master/source/expansion/cleaner.py"
    click EX_converter "https://github.com/joeanamier/xhs-downloader/blob/master/source/expansion/converter.py"
    click EX_error "https://github.com/joeanamier/xhs-downloader/blob/master/source/expansion/error.py"
    click EX_file_folder "https://github.com/joeanamier/xhs-downloader/blob/master/source/expansion/file_folder.py"
    click EX_namespace "https://github.com/joeanamier/xhs-downloader/blob/master/source/expansion/namespace.py"
    click EX_truncate "https://github.com/joeanamier/xhs-downloader/blob/master/source/expansion/truncate.py"
    click TR_translate "https://github.com/joeanamier/xhs-downloader/blob/master/source/translation/translate.py"
    click LC_locale "https://github.com/joeanamier/xhs-downloader/tree/master/locale"
    click STATIC_assets "https://github.com/joeanamier/xhs-downloader/tree/master/static"
    click DEP_docker "https://github.com/joeanamier/xhs-downloader/tree/master/Dockerfile"
    click DEP_cicd "https://github.com/joeanamier/xhs-downloader/tree/master/.github/workflows"
    click DEP_dependencies "https://github.com/joeanamier/xhs-downloader/blob/master/requirements.txt"
```
