# audionut/upload-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/audionut/upload-assistant
- Repository: https://github.com/audionut/upload-assistant

## Overview

##### Main components
a. User Interfaces:
- CLI Interface – with the main entry point in “upload.py” and supporting modules in “src/console.py”.
- Discord Bot Interface – provided by “discordbot.py” and “cogs/commands.py” to possibly issue commands via Discord.
b. Core Application Logic:
- Processing and Parsing Modules – in “src” (for media info parsing, command arguments handling, torrent creation, etc.).
- Tracker Integration Modules – found in “src/trackers” where each tracker (e.g., ACM, BHDTV, BLU, etc.) has its own integration module.
- Job Coordination Modules – e.g., “src/queuemanage.py” and “src/uphelper.py” for handling tasks and upload workflows.
c. External Dependencies and Binaries:
- BDInfo – binaries found under “bin/BDInfo” for media information extraction.
- mkbrr – a set of cross-platform binaries under “bin/mkbrr” for certain operations.
- External tools – MediaInfo, ffmpeg, and mono (as described in the README requirements), which are not part of the repository but are significant to how the system works.
d. Configuration/Data Components:
- Config/templates in “data” – including “example-config.py”, cookie data, version file, and templates for torrent description or other text processing.
e. Docker/CI Pipeline:
- Dockerfile in the root and GitHub workflows under “.github/workflows” – illustrating deployment/CD integration.

##### Relationships and interactions
- The CLI (upload.py) serves as the entry point. When executed, it passes the target upload directory and additional arguments to the underlying modules.
- The core processing modules in “src” take over: these modules interact with external binaries (BDInfoCLI, mkbrr) to generate and parse metadata.
- Based on metadata and file analysis, the application consults various tracker integration modules (under “src/trackers”) to prepare proper formatted uploads and to check for existing releases.
- There is a pipeline where data flows from initial file input → metadata extraction → data normalization (e.g., converting absolute season/episode numbering using modules like “src/getseasonep.py”) → torrent creation (“src/torrentcreate.py”) → final upload operations.
- The Discord bot (discordbot.py and “cogs”) can serve as an alternative interface to trigger these actions.
- The CI/CD setup (via GitHub workflows and Dockerfile) shows that the system is built to support continuous integration, testing, and Docker-based deployment.

##### Architectural patterns and design principles
- Modular design: The clear separation between generic processing (in “src”) and tracker-specific implementations (in “src/trackers”) allows for extensibility.
- Separation of concerns: User interface (CLI and Discord commands) is segregated from business logic.
- Dependency on external software: The architecture explicitly relies on third-party tools (MediaInfo, BDInfo, ffmpeg) and external APIs (like TMDb, IMDb).
- CI/CD and containerization: Built-in support for Docker and automated workflows make the project production-ready and easy to deploy across environments.

##### Relevant Technologies and Libraries
- Python 3.9 or above – the code base relies on Python modules listed in “requirements.txt”.
- External binaries and tools: BDInfoCLI, mkbrr, MediaInfo, ffmpeg, mono.
- Docker – via the provided Dockerfile and documented usage in the README.
- GitHub Actions workflows for linting, building Docker images, and automatic updates.

a. Begin by drawing a high-level overview that separates User Interfaces (CLI and Discord Bot) from Core Processing.
b. How the Core Processing layer interacts with external services/binaries (like BDInfo, mkbrr, MediaInfo, ffmpeg) and the configuration/templates layer.
c. Flow from user input (via CLI commands) to various processing steps:
- Input Handling → Metadata Extraction → Tracker and Torrent Preparation → Upload Action.
- CLI Interface (upload.py)
- Discord Bot Interface (discordbot.py, cogs)
- Core Application Modules (group modules in “src”)
- Tracker Modules (group modules in “src/trackers”)
- External Dependencies (BDInfo, mkbrr, MediaInfo, ffmpeg, mono)
- Data/Configuration (files in “data”)
- CI/CD and Deployment Pipeline (Dockerfile and GitHub workflows)

##### Essential Elements
- All major components with clear labels.
- Interfaces (CLI, Discord)
- Core processing modules (parsing, conversion, torrent creation)
- External integrations (third-party tools and API connections)
- Supporting infrastructure (CI/CD, Docker)
- Any notable dependencies or decision points (such as when choosing which tracker module to route data to based on the upload type).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Interface (upload.py)"]:::interface
        Console["Console Module (src/console.py)"]:::interface
        Discord["Discord Bot Interface (discordbot.py)"]:::interface
        DiscordCmd["Command Module (cogs/commands.py)"]:::interface
    end

    %% Core Processing Modules
    subgraph "Core Processing"
        CoreCtrl["Core Controller (src)"]:::processing
        MetaExtract["Metadata Extraction (src/exportmi.py)"]:::processing
        IMDBInt["IMDB Integration (src/imdb.py)"]:::processing
        TorrentCreate["Torrent Creation (src/torrentcreate.py)"]:::processing
        JobCoord["Job Coordination (src/queuemanage.py & src/uphelper.py)"]:::processing
    end

    %% Tracker Integration Modules
    subgraph "Tracker Integration"
        Tracker["Tracker Modules (src/trackers)"]:::processing
    end

    %% External Dependencies & Binaries
    subgraph "External Dependencies"
        BDInfo["BDInfo Binaries"]:::external
        mkbrr["mkbrr Binaries"]:::external
        Tools["External Tools (MediaInfo,ffmpeg,mono)"]:::external
    end

    %% Configuration and Data
    subgraph "Configuration & Data"
        Config["Config & Templates (data)"]:::config
    end

    %% CI/CD & Deployment Pipeline
    subgraph "CI/CD & Deployment"
        Docker["Docker Deployment (Dockerfile)"]:::ci
        Workflows["CI/CD Workflows (.github/workflows)"]:::ci
    end

    %% Interactions from User Interfaces to Core Processing
    CLI -->|"triggers"| CoreCtrl
    Console -->|"supports"| CoreCtrl
    Discord -->|"alternativeTrigger"| CoreCtrl
    DiscordCmd -->|"commands"| CoreCtrl

    %% Core Processing workflow
    CoreCtrl -->|"initiateExtraction"| MetaExtract
    MetaExtract -->|"fetchIMDBData"| IMDBInt
    IMDBInt -->|"createTorrent"| TorrentCreate
    TorrentCreate -->|"coordinateUpload"| JobCoord

    %% Core Controller also interacts with Tracker Integration and Configuration
    CoreCtrl -->|"selectTracker"| Tracker
    CoreCtrl -->|"readConfig"| Config

    %% Metadata extraction uses external dependencies
    MetaExtract -->|"usesBDInfo"| BDInfo
    MetaExtract -->|"usesMkbrr"| mkbrr
    MetaExtract -->|"leveragesTools"| Tools

    %% Job Coordination orchestrates interaction with trackers
    JobCoord -->|"finalizeUpload"| Tracker

    %% CI/CD impacts the system components
    Docker -.->|"builds"| CLI
    Docker -.->|"builds"| CoreCtrl
    Docker -.->|"builds"| Tracker
    Docker -.->|"builds"| BDInfo
    Workflows -.->|"tests&Deploys"| CoreCtrl

    %% Click Events
    click CLI "https://github.com/audionut/upload-assistant/blob/master/upload.py"
    click Console "https://github.com/audionut/upload-assistant/blob/master/src/console.py"
    click Discord "https://github.com/audionut/upload-assistant/blob/master/discordbot.py"
    click DiscordCmd "https://github.com/audionut/upload-assistant/blob/master/cogs/commands.py"
    click MetaExtract "https://github.com/audionut/upload-assistant/blob/master/src/exportmi.py"
    click IMDBInt "https://github.com/audionut/upload-assistant/blob/master/src/imdb.py"
    click TorrentCreate "https://github.com/audionut/upload-assistant/blob/master/src/torrentcreate.py"
    click JobCoord "https://github.com/audionut/upload-assistant/blob/master/src/queuemanage.py"
    click Tracker "https://github.com/audionut/upload-assistant/tree/master/src/trackers"
    click BDInfo "https://github.com/audionut/upload-assistant/tree/master/bin/BDInfo"
    click mkbrr "https://github.com/audionut/upload-assistant/tree/master/bin/mkbrr"
    click Config "https://github.com/audionut/upload-assistant/tree/master/data"
    click Docker "https://github.com/audionut/upload-assistant/tree/master/Dockerfile"
    click Workflows "https://github.com/audionut/upload-assistant/tree/master/.github/workflows"

    %% Class Definitions for colour coding
    classDef interface fill:#f9c,stroke:#333,stroke-width:2px;
    classDef processing fill:#9f9,stroke:#333,stroke-width:2px;
    classDef external fill:#ccf,stroke:#333,stroke-width:2px;
    classDef config fill:#fcf,stroke:#333,stroke-width:2px;
    classDef ci fill:#ffd,stroke:#333,stroke-width:2px;
```
