# zephyris-pro/vkdownloader architecture

> Architecture diagram of the GitHub repository zephyris-pro/vkdownloader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zephyris-pro/vkdownloader
- Repository: https://github.com/zephyris-pro/vkdownloader

## Overview

##### Project Type and Purpose
- This is a command-line utility (open-source tool) written in Python.
- Purpose: scrape and download files (PDFs, images, audio, etc.) from a specified URL or list of URLs (batch mode).

##### Top-Level File Structure and Roles
- vk_downloader.py – core downloader CLI.
- batch_download_file_creator.py – reads a text file of URLs, extracts titles, generates a Windows batch (.cmd) script to drive vk_downloader.exe for each URL.
- requirements.txt – Python dependencies.
- build.{sh,bat} & install.{sh,bat} – scripts to build a frozen/packaged executable (vk_downloader.exe) and install dependencies.
- assets/ – any static resources (e.g., logos, sample templates).

##### Main Components
a. User/CLI Layer
- User’s shell (bash/cmd) invoking either vk_downloader.py or the generated batch_download.cmd.
b. Argument Parser
- Parses URL, output_dir, file_type, threads flags (uses argparse).
c. Download Engine
- HTTP Client Module (e.g., requests)
- Concurrency/Thread Pool managing simultaneous downloads
d. HTML Parser & Title Extractor
- CSS selector for div.bt_title
- Fallback to <title> tag or regex
e. File Manager
- Creates output directories
- Saves binary files to disk
f. Batch Script Generator
- Reads URLs from text file
- Invokes title extractor logic to name folders
- Writes batch_download.cmd containing repeated vk_downloader.exe invocations with flags
g. External Service
- VK.com web server (target of HTTP requests)
h. Build & Install Subsystem (auxiliary)
- build.sh/.bat: package into an executable (e.g., via PyInstaller)
- install.sh/.bat: install dependencies

##### Relationships and Data Flow
- User → (CLI) Argument Parser → Download Engine
- Download Engine ↔ External Service (HTTP GETs)
- Download Engine → File Manager (write files)
- batch_download_file_creator.py → Batch Script Generator → batch_download.cmd
- batch_download.cmd (shell script) → multiple vk_downloader.exe invocations → same download flow

##### Architectural Patterns & Principles
- Single-responsibility: separate modules for downloading vs. batch generation.
- Modular CLI design: each script has its own entry point and argument parsing.
- Layered I/O: clear separation between network I/O, parsing, and filesystem I/O.

##### Technologies & Frameworks
- Python 3.x
- requests (HTTP client)
- argparse (CLI argument parsing)
- threading or concurrent.futures for multi-threaded downloads
- PyInstaller (or similar) for packaging into vk_downloader.exe
- Windows batch scripting (batch_download.cmd)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User/CLI Layer"
        Shell["User Shell (bash/cmd)"]:::external
        CLI["CLI & Arg Parser\n(vk_downloader.py)"]:::runtime
    end

    subgraph "Core Components"
        DL["Download Engine\n(HTTP Client & Threads)"]:::runtime
        Parser["HTML Parser & Title Extractor"]:::runtime
        FileMgr["File Manager"]:::runtime
    end

    VK["VK.com Web Server"]:::external

    subgraph "Batch Generation"
        BatchGen["Batch Script Generator\n(batch_download_file_creator.py)"]:::batch
        BatchFile["batch_download.cmd"]:::batchfile
    end

    subgraph "Build & Install"
        Build["Build Scripts\n(build.sh/.bat)"]:::build
        Install["Install Scripts\n(install.sh/.bat)"]:::build
        Manifest["requirements.txt"]:::manifest
        Assets["assets/"]:::asset
    end

    Shell --> CLI
    CLI --> DL
    DL --> Parser
    Parser --> DL
    DL --> FileMgr
    DL --> VK
    VK --> DL

    Shell --> BatchGen
    BatchGen --> BatchFile
    BatchFile -->|"invokes vk_downloader.exe"| DL

    Build --> CLI
    Install --> Manifest
    Manifest -.-> CLI
    Assets -.-> CLI

    click CLI "https://github.com/zephyris-pro/vkdownloader/blob/main/vk_downloader.py"
    click BatchGen "https://github.com/zephyris-pro/vkdownloader/blob/main/batch_download_file_creator.py"
    click Build "https://github.com/zephyris-pro/vkdownloader/blob/main/build.sh"
    click Build "https://github.com/zephyris-pro/vkdownloader/blob/main/build.bat"
    click Install "https://github.com/zephyris-pro/vkdownloader/blob/main/install.sh"
    click Install "https://github.com/zephyris-pro/vkdownloader/blob/main/install.bat"
    click Manifest "https://github.com/zephyris-pro/vkdownloader/blob/main/requirements.txt"
    click Assets "https://github.com/zephyris-pro/vkdownloader/tree/main/assets/"

    classDef runtime fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef build fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef batch fill:#FFFACD,stroke:#333,stroke-width:1px;
    classDef batchfile fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef asset fill:#D8BFD8,stroke:#333,stroke-width:1px;
    classDef manifest fill:#E0FFFF,stroke:#333,stroke-width:1px;
```
