# c0d3d3v/moodle-dl architecture

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

- Interactive diagram: https://gitdiagram.com/c0d3d3v/moodle-dl
- Repository: https://github.com/c0d3d3v/moodle-dl

## Overview

##### Project Type and Purpose
- Project Type: A command-line interface (CLI) application.
- Purpose: To interact with a Moodle instance via its mobile API, download course files (including assignments, videos, forum content, etc.), and notify the user via multiple channels (Telegram, Discord, XMPP, Mail, and others).
- Key Use Cases: Initial configuration via a CLI wizard, automatic file downloads (with “only new” file fetching), and multi-channel notification sending.

##### File Structure
- Main Package Folder: “moodle_dl” serves as the core package.
- CLI Components: The “moodle_dl/cli” directory contains the configuration wizard, database manager, and Moodle wizard for guiding initial setup.
- Downloader Module: Located in “moodle_dl/downloader” and its “extractors” subdirectory (with individual extractors for platforms like echo360, googledrive, opencast, etc.). This module is responsible for interfacing with the Moodle mobile API to download various types of course material.
- Moodle Interaction: “moodle_dl/moodle” deals with handling cookies, core interactions with Moodle (core_handler, mods for specific Moodle modules like assign, quiz, etc.), and result building.
- Notifications: “moodle_dl/notifications” is organized into submodules for different notification channels (console, discord, mail, ntfy, telegram, xmpp). Each contains its own service, formatter, and shooter components.
- Supporting Modules: “moodle_dl/config.py”, “moodle_dl/database.py”, “moodle_dl/utils.py”, and “moodle_dl/types.py” provide configuration management, persistent storage, utility functions, and type definitions.
- Entry Point: “moodle_dl/main.py” which likely ties together the CLI flow and triggers the download/notification process.
- Build & Packaging: Files like “setup.py”, “pyproject.toml”, “MANIFEST.in”, and Dockerfile indicate packaging and containerization support.

##### Key Architectural Components & Their Relationships
- CLI/Configuration Interface:
- Components: moodle_dl/cli (config_wizard.py, moodle_wizard.py, database_manager.py, notifications_wizard.py)
- Role: Guides the user through setup, configuration, and initial login/token management.
- Interaction: Invokes modules from the configuration, Moodle, and notifications components.
- Downloader:
- Components: moodle_dl/downloader (download_service.py, task.py) and its plug-in extractors.
- Role: Handles the logic for downloading course materials. Utilizes a variety of extractors to manage different external resources (e.g., videos through Googledrive, opencast).
- Interaction: Communicates with the Moodle module for fetching course content and the database or file system for determining file states (new/old).
- Moodle Interface:
- Components: moodle_dl/moodle (cookie_handler.py, core_handler.py, various mods, moodle_service.py, request_helper.py).
- Role: Manages Moodle-specific operations such as cookie generation, processing course content, and handling specific Moodle modules.
- Interaction: Called by the downloader and indirectly by CLI tools for authentication and session management.
- Notifications:
- Components: moodle_dl/notifications (divided by channel—console, discord, mail, ntfy, telegram, xmpp).
- Role: Formats and sends out notifications containing summaries or contents of downloaded data.
- Interaction: Receives data from downloader and passes notifications to external systems.
- Supporting Utilities:
- Components: Configuration, Database, Utils.
- Role: Provide common functionality like reading/writing configuration (including secure token management), logging, and versioning.
- Interaction: Used across various modules for standardized operations.

##### Architectural Patterns and Design Principles
- Modularity: Each major functionality—downloading, Moodle interaction, notifications—is encapsulated in dedicated modules/directories. The use of “extractors” is a plug-in-like design to handle different external resources.
- CLI-Driven Workflow: The application leverages a CLI pattern to guide configuration and process execution, which then orchestrates interactions among modules.
- Separation of Concerns: Clear segmentation is seen between handling Moodle-specific operations (in “moodle”) and cross-cutting concerns such as notifications and file downloads.
- Extensibility: With clear submodules (especially in notifications and download extractors), the architecture supports easy extension or integration with new services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI/Configuration Interface
    subgraph "CLI/Configuration Interface"
        CLI_Config["CLI Wizard, DB Manager, Moodle Wizard, Notifications Wizard"]:::cli
    end
    click CLI_Config "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/cli"

    %% Entry Point
    subgraph "Entry Point"
        MainPoint["Main (Entry Point)"]:::entry
    end
    click MainPoint "https://github.com/c0d3d3v/moodle-dl/blob/main/moodle_dl/main.py"

    %% Downloader & Extractors
    subgraph "Downloader & Extractors"
        DownloadService["Download Service & Task"]:::downloader
        Extractors["Extractors Plug-In"]:::extractor
    end
    click DownloadService "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/downloader"
    click Extractors "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/downloader/extractors"

    %% Moodle API/Session Management
    subgraph "Moodle API/Session Management"
        MoodleService["Moodle Service, Cookie Handler, Core Handler, Mods, Request Helper, Result Builder"]:::moodle
    end
    click MoodleService "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/moodle"

    %% Notification Services
    subgraph "Notification Services"
        ConsoleNotif["Console Notifier"]:::notification
        DiscordNotif["Discord Notifier"]:::notification
        MailNotif["Mail Notifier"]:::notification
        NtfyNotif["Ntfy Notifier"]:::notification
        TelegramNotif["Telegram Notifier"]:::notification
        XMPPNotif["XMPP Notifier"]:::notification
    end
    click ConsoleNotif "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/notifications/console"
    click DiscordNotif "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/notifications/discord"
    click MailNotif "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/notifications/mail"
    click NtfyNotif "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/notifications/ntfy"
    click TelegramNotif "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/notifications/telegram"
    click XMPPNotif "https://github.com/c0d3d3v/moodle-dl/tree/main/moodle_dl/notifications/xmpp"

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        ConfigUtil["Config Management (config.py)"]:::utils
        DatabaseUtil["Database (database.py)"]:::utils
        UtilsUtil["Utility Functions (utils.py)"]:::utils
        TypesUtil["Type Definitions (types.py)"]:::utils
    end
    click ConfigUtil "https://github.com/c0d3d3v/moodle-dl/blob/main/moodle_dl/config.py"
    click DatabaseUtil "https://github.com/c0d3d3v/moodle-dl/blob/main/moodle_dl/database.py"
    click UtilsUtil "https://github.com/c0d3d3v/moodle-dl/blob/main/moodle_dl/utils.py"
    click TypesUtil "https://github.com/c0d3d3v/moodle-dl/blob/main/moodle_dl/types.py"

    %% External Dependencies
    ExternalMoodle["Moodle mobile API"]:::external
    ExternalFS["File System (Downloads)"]:::external
    ExternalNotif["Notification Endpoints"]:::external
    FFMPEG["FFMPEG"]:::external
    Docker["Docker Container"]:::external

    %% Relationships
    CLI_Config -->|"configures"| MainPoint
    MainPoint -->|"initiates"| DownloadService

    DownloadService -->|"invokes"| Extractors
    DownloadService -->|"fetches"| MoodleService
    DownloadService -->|"checks"| DatabaseUtil
    DownloadService -->|"saves-to"| ExternalFS
    DownloadService -->|"processes-videos"| FFMPEG

    MoodleService -->|"calls"| ExternalMoodle

    DownloadService -->|"notifies"| ConsoleNotif
    DownloadService -->|"notifies"| DiscordNotif
    DownloadService -->|"notifies"| MailNotif
    DownloadService -->|"notifies"| NtfyNotif
    DownloadService -->|"notifies"| TelegramNotif
    DownloadService -->|"notifies"| XMPPNotif

    ConsoleNotif -->|"sends"| ExternalNotif
    DiscordNotif -->|"sends"| ExternalNotif
    MailNotif -->|"sends"| ExternalNotif
    NtfyNotif -->|"sends"| ExternalNotif
    TelegramNotif -->|"sends"| ExternalNotif
    XMPPNotif -->|"sends"| ExternalNotif

    MainPoint -->|"containerized-by"| Docker

    %% Styles
    classDef cli fill:#fceabb,stroke:#e3a21a,stroke-width:2px;
    classDef entry fill:#d5e8d4,stroke:#82b366,stroke-width:2px;
    classDef downloader fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px;
    classDef extractor fill:#e1d5e7,stroke:#9673a6,stroke-width:2px;
    classDef moodle fill:#fff2cc,stroke:#d6b656,stroke-width:2px;
    classDef notification fill:#f8cecc,stroke:#b85450,stroke-width:2px;
    classDef utils fill:#e4dfda,stroke:#93846b,stroke-width:2px;
    classDef external fill:#ffffff,stroke:#000000,stroke-dasharray: 5 5,stroke-width:2px;
```
