# r0oth3x49/udemy-dl architecture

> Architecture diagram of the GitHub repository r0oth3x49/udemy-dl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/r0oth3x49/udemy-dl
- Repository: https://github.com/r0oth3x49/udemy-dl

## Overview

This is a **Python 3 CLI utility** (not a service) that:
- Authenticates to **Udemy** (username/password or cookie/access_token).
- Fetches **course metadata + curriculum structure** (chapters/lectures).
- Resolves **video streams** (direct MP4 and/or **HLS/m3u8**) + assets + subtitles.
- Downloads to local disk with **resume/progress/logging**.
- Optionally runs **FFmpeg** for HLS handling and **VTT→SRT** conversion.

##### Read the repo structure as architecture boundaries
Top level:
- `udemy-dl.py` → **entrypoint / CLI** (argument parsing and orchestration).
- `requirements.txt` → runtime deps (requests, cloudscraper, etc.).
- `udemy/` package → the real “application” split into modules:
- `udemy/auth.py` → login/auth flows
- `udemy/session.py` → session + cookie/token persistence (“proper session management”, `--cache`)
- `udemy/extract.py` → extract course structure, lecture info, stream URLs, subtitles/assets links
- `udemy/udemy.py` → likely a **facade/service layer** that coordinates auth/session/extract/download
- `udemy/ffmpeg.py` → integration with external FFmpeg binary (HLS downloads)
- `udemy/vtt2srt.py` → subtitles conversion
- `udemy/progress.py` → progress indicators / resume support
- `udemy/logger.py` → logging errors/warnings
- `udemy/sanitize.py` → safe filenames/path handling
- `udemy/utils.py`, `udemy/shared.py`, `udemy/internal.py`, `udemy/compat.py` → shared helpers, compatibility glue, constants, internal APIs

This implies a **single-process layered CLI**:
CLI → Core orchestrator → Session/Auth + Extract → Download pipeline → Post-processing → Filesystem output.

##### Auth
- cookies token path (`-k cookies.txt`) OR username/password (`-u/-p`)
- session caching (`--cache`)
##### Extraction
- fetch course page/metadata
- build curriculum list (chapters/lectures)
- resolve per-lecture:
- stream type (MP4 vs HLS)
- subtitles list (VTT)
- assets list
##### Download loop
- sanitize filenames
- for each lecture:
- download video (direct HTTP) OR invoke FFmpeg for HLS
- resume support / progress updates
- download subtitles/assets depending on flags
- convert VTT→SRT if configured (and keep VTT if `--keep-vtt`)
##### Logging + final summary

- HLS vs non-HLS (`--skip-hls`)
- subtitles only / skip subtitles (`--sub-only`, `--skip-sub`)
- assets only / skip assets (`--assets-only`, `--skip-assets`)
- info-only mode (`--info`)

##### Architectural patterns/design principles to explicitly call out
- **Facade/orchestrator**: `udemy/udemy.py` coordinating modules.
- **Session management**: single persistent session object reused across requests (resume/login stability).
- **Pipeline**: Extract → Select (chapters/lectures/quality) → Download → Post-process.
- **Adapter pattern** for external tool: `ffmpeg.py` wraps FFmpeg invocation.
- **Cross-cutting concerns**: logging, progress, sanitization.

##### Context: User ↔ CLI ↔ Udemy; CLI ↔ Filesystem; CLI ↔ FFmpeg.
4. **decision annotations** for flags (`--info`, `--skip-hls`, `--sub-only`, `--cache`, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1: System Context
  %% =========================
  subgraph "System Context (C4-L1)"
    U["User (Terminal)"]:::actor
    CLI["udemy-dl (Local CLI Executable)"]:::cli

    NET["Internet / Network"]:::boundary
    UDEMY{{"Udemy Web Platform (APIs/CDN)"}}:::external
    CF{{"Cloudflare / Anti-bot Layer"}}:::external

    FS[("Local Filesystem\n(output dir, cookies.txt, logs, cache)")]:::storage
    FFMPEG["FFmpeg (external executable)"]:::os
  end

  U -->|"runs CLI;flags;credentials"| CLI
  CLI -->|"HTTPS requests"| NET
  NET -->|"HTTPS to endpoints"| CF
  CF -->|"proxy/mitigate"| UDEMY
  CLI -->|"local file IO:read/write"| FS
  CLI -->|"subprocess:spawn"| FFMPEG

  %% =========================
  %% Level 2: Container/Component view (single-process CLI)
  %% =========================
  subgraph "udemy-dl Internals (C4-L2/L3 Components)"
    direction TB

    ENTRY["CLI Entrypoint\n(arg parsing, orchestration)"]:::cli

    subgraph "Core Library (udemy package)"
      direction TB

      API["Package Public API\nudemy/__init__.py"]:::internal
      FACADE["Udemy Client / Facade\n(main coordinator)"]:::internal

      subgraph "Auth & Session"
        direction TB
        AUTH["Authenticator\n(login/cookies/token)"]:::internal
        GETPASS["Credential Prompt Helper"]:::internal
        SESSION["Session Manager\n(cookies/token persistence, --cache)"]:::internal
      end

      subgraph "Discovery / Extraction"
        direction TB
        EXTRACT["Course Extractor\n(metadata,curriculum,streams,subs,assets)"]:::internal
      end

      subgraph "Download & Processing Pipeline"
        direction TB

        HTTP["HTTP Fetcher\n(requests/cloudscraper)"]:::library
        PROG["Progress / Resume"]:::internal
        SAN["Filename/Path Sanitizer"]:::internal
        LOG["Logging"]:::internal

        subgraph "Post-processing"
          direction TB
          FFMAD["FFmpeg Adapter\n(HLS/m3u8 handling)"]:::internal
          VTT["Subtitles Processor\n(VTT→SRT)"]:::internal
        end

        UI["Terminal UI / Colorized Output\n(banner, colors)"]:::internal
        SHARED["Shared Constants / Common Routines"]:::internal
        UTILS["Shared Helpers / Utilities"]:::internal
        INTERNALS["Internal Helpers / Internal APIs"]:::internal
        COMPAT["Compatibility Layer"]:::internal
      end
    end

    NOTE_DRM["Note: DRM-protected/encrypted videos\nare not bypassed;may be skipped"]:::note
  end

  %% Entry wiring
  CLI -->|"executes"| ENTRY
  ENTRY -->|"invoke download(course_url, options)"| FACADE
  API -->|"exports/imports"| FACADE

  %% Facade interactions
  FACADE -->|"auth flow"| AUTH
  AUTH -->|"prompt missing creds"| GETPASS
  FACADE -->|"load/save session;attach headers/cookies"| SESSION
  FACADE -->|"fetch curriculum;resolve streams/assets/subs"| EXTRACT

  %% Network access
  SESSION -->|"HTTPS via session"| HTTP
  AUTH -->|"HTTPS login endpoints"| HTTP
  EXTRACT -->|"HTTPS course/lecture metadata"| HTTP
  HTTP -->|"HTTPS"| NET
  NET -->|"HTTPS"| CF
  CF -->|"HTTPS"| UDEMY

  %% Download loop + files
  FACADE -->|"download loop"| HTTP
  FACADE -->|"sanitize names/paths"| SAN
  FACADE -->|"progress + resume"| PROG

  HTTP -->|"mp4/vtt/assets download"| FS
  SAN -->|"create safe dirs/filenames"| FS
  PROG -->|"resume partials"| FS

  %% HLS path
  HTTP -->|"detect m3u8/HLS manifest"| FFMAD
  FFMAD -->|"subprocess:ffmpeg m3u8→mp4"| FFMPEG
  FFMPEG -->|"writes merged media"| FS

  %% Subtitle conversion
  HTTP -->|"download .vtt"| FS
  VTT -->|"convert vtt→srt"| FS

  %% Cross-cutting
  ENTRY -->|"status output"| UI
  FACADE -->|"status output"| UI
  PROG -->|"progress rendering"| UI

  ENTRY -->|"info/warn/error"| LOG
  FACADE -->|"info/warn/error"| LOG
  AUTH -->|"info/warn/error"| LOG
  SESSION -->|"info/warn/error"| LOG
  EXTRACT -->|"info/warn/error"| LOG
  HTTP -->|"info/warn/error"| LOG
  FFMAD -->|"info/warn/error"| LOG
  VTT -->|"info/warn/error"| LOG
  LOG -->|"write logs"| FS

  %% Shared helpers dependencies
  AUTH -->|"helpers"| UTILS
  SESSION -->|"helpers"| SHARED
  EXTRACT -->|"helpers"| INTERNALS
  HTTP -->|"compat glue"| COMPAT

  %% Decision/flags annotations
  FLAGS["Flags / Decision Points\n--info (no download)\n--skip-hls (avoid ffmpeg)\n--sub-only / --skip-sub\n--assets-only / --skip-assets\n--cache (session persistence)\n--keep-vtt (retain VTT)"]:::note
  ENTRY -.->|"controls"| FLAGS
  FLAGS -.-> FACADE

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click CLI "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy-dl.py"
  click ENTRY "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy-dl.py"
  click FACADE "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/udemy.py"
  click API "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/__init__.py"
  click AUTH "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/auth.py"
  click GETPASS "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/getpass.py"
  click SESSION "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/session.py"
  click EXTRACT "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/extract.py"
  click FFMAD "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/ffmpeg.py"
  click VTT "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/vtt2srt.py"
  click PROG "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/progress.py"
  click LOG "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/logger.py"
  click SAN "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/sanitize.py"
  click UI "https://github.com/r0oth3x49/udemy-dl/tree/master/udemy/colorized/"
  click UTILS "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/utils.py"
  click SHARED "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/shared.py"
  click INTERNALS "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/internal.py"
  click COMPAT "https://github.com/r0oth3x49/udemy-dl/blob/master/udemy/compat.py"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#111827,stroke:#374151,color:#F9FAFB,stroke-width:1.5px
  classDef cli fill:#1D4ED8,stroke:#1E40AF,color:#FFFFFF,stroke-width:1.5px
  classDef internal fill:#2563EB,stroke:#1E40AF,color:#FFFFFF,stroke-width:1.2px
  classDef external fill:#F59E0B,stroke:#B45309,color:#111827,stroke-width:1.5px
  classDef os fill:#22C55E,stroke:#15803D,color:#052e16,stroke-width:1.5px
  classDef storage fill:#10B981,stroke:#047857,color:#052e16,stroke-width:1.5px
  classDef library fill:#9CA3AF,stroke:#4B5563,color:#111827,stroke-width:1.2px
  classDef note fill:#FEF3C7,stroke:#D97706,color:#111827,stroke-width:1.2px
  classDef boundary fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-dasharray: 4 3,stroke-width:1.2px
```
