# efeckc17/youtubego architecture

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

- Interactive diagram: https://gitdiagram.com/efeckc17/youtubego
- Repository: https://github.com/efeckc17/youtubego

## Overview

##### Project type and purpose
- This is a standalone desktop application (“YoutubeGO 5.0”) written in Python 3.7+ with a PySide6 (Qt) GUI.
- It’s a modern media downloader: fetches video/audio streams from the web (YouTube, Vimeo, HTTP), manages profiles, schedules and queues, uses FFmpeg for processing, and auto-updates itself.

##### High-level architecture overview
- The code is modularized into three main layers:
a. Presentation/UI Layer (ui/)
b. Application/Core Logic Layer (core/)
c. Infrastructure/External Dependencies

##### Main components
- Entry point: main.py → instantiates Application and MainWindow
- ui/main_window.py → coordinates menus, side menu, status bar, pages
- ui/pages/… → seven page modules (home, mp4, mp3, queue, history, scheduler, profile, settings)
- ui/components/… → reusable widgets (AnimatedButton, DragDropLineEdit, LogDock, TrayIcon, ThemeManager, SearchPopup, ProfileManager, etc.)
- ui/dialogs/… → dialogs for profile editing, queue addition, scheduler creation
- ui/layouts/… → layout abstractions (side menu, top bar, status bar)
- ui/themes/*.qss → style sheets for dark/light themes

- core/downloader.py → orchestrates downloads via yt-dlp & requests, handles formats
- core/ffmpeg_checker.py → detects/validates FFmpeg binary, prompts user if missing
- core/history.py → persists and queries download history (likely via flat files or SQLite)
- core/profile.py → load/save user profile (paths, display name, social links, export/import)
- core/updater.py → checks GitHub Releases API, downloads and installs updates
- core/utils.py → shared utilities (logging, path management, concurrency helpers)
- core/version.py → app version constant and comparison logic

- yt-dlp library → low-level downloader + metadata extraction
- requests library → HTTP interactions (fallback, metadata, API calls)
- FFmpeg binary → audio/video processing (merging, transcoding)
- File System → storing profiles, history, playlists, temporary files, caches
- Network/Internet → target platforms (YouTube, Vimeo, HTTP streams)
- GitHub Releases API → version check & auto-update

##### Interactions & data flow
- UI Layer components emit events/signals → invoke Core Logic APIs (Downloader, Scheduler, etc.)
- Core Logic orchestrates download tasks:
- Downloader uses yt-dlp & requests → writes to File System → updates History
- FFmpegChecker → ensures FFmpeg is in PATH before extraction steps
- Updater → polls GitHub → downloads installer or patch → triggers restart
- Scheduler enqueues tasks in Downloader with timestamp triggers
- Profile import/export reads/writes zip on File System
- System Tray (TrayIcon) listens for app minimize/restore events

##### Architectural patterns & principles
- Layered Architecture: clear separation between UI and business logic
- MVC-like flavor in pages: each page module handles its own view + connects to Core services
- Single Responsibility: each core module focuses on one domain concept (download, profile, update, etc.)
- Event-Driven / Signal-Slot (Qt) for decoupled communication
- Dependency Injection (passing core services into UI pages)

##### Detail
- Cross-cutting concerns: auto-updater, theme management, error logging.
- User actions (drag & drop, menu commands) flowing into the UI layer and then into the core layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer" 
        style UI_layer fill:#D6E9FF,stroke:#2B7CE9
        EntryPoint["Entry Point\nmain.py"]:::ui
        MainWindow["Main Window"]:::ui
        subgraph "Pages" 
            style pages fill:#E8F2FF,stroke:#2B7CE9
            HomePage["Home Page"]:::ui
            MP4Page["MP4 Download Page"]:::ui
            MP3Page["MP3 Download Page"]:::ui
            QueuePage["Queue Page"]:::ui
            HistoryPage["History Page"]:::ui
            SchedulerPage["Scheduler Page"]:::ui
            ProfilePage["Profile Page"]:::ui
            SettingsPage["Settings Page"]:::ui
        end
        subgraph "Components"
            style components fill:#E8F2FF,stroke:#2B7CE9
            AnimatedButton["Animated Button"]:::ui
            DragDropLineEdit["Drag & Drop Line Edit"]:::ui
            LogDock["Log Dock"]:::ui
            MenuBar["Menu Bar"]:::ui
            ProfileManagerWidget["Profile Manager Widget"]:::ui
            SearchPopup["Search Popup"]:::ui
            SearchSystemHelper["Search System Helper"]:::ui
            ThemeManager["Theme Manager"]:::ui
            TrayIcon["System Tray Icon"]:::ui
        end
        subgraph "Dialogs"
            style dialogs fill:#E8F2FF,stroke:#2B7CE9
            ProfileDialog["Profile Edit Dialog"]:::ui
            QueueAddDialog["Queue Add Dialog"]:::ui
            ScheduleAddDialog["Scheduler Add Dialog"]:::ui
        end
        subgraph "Layouts"
            style layouts fill:#E8F2FF,stroke:#2B7CE9
            SideMenuLayout["Side Menu Layout"]:::ui
            TopBarLayout["Top Bar Layout"]:::ui
            StatusBarLayout["Status Bar Layout"]:::ui
        end
        subgraph "Themes"
            style themes fill:#E8F2FF,stroke:#2B7CE9
            DarkTheme["Dark Theme (.qss)"]:::ui
            LightTheme["Light Theme (.qss)"]:::ui
        end
    end

    %% Core Layer
    subgraph "Core Logic Layer"
        style core_layer fill:#DFFFE0,stroke:#2B8E0D
        Downloader["Download Orchestrator"]:::core
        FFmpegChecker["FFmpeg Checker"]:::core
        HistoryStore["Download History Store"]:::core
        ProfileManagerCore["Profile Manager"]:::core
        Updater["Auto-Updater Service"]:::core
        Utils["Shared Utilities"]:::core
        Version["Version Constants"]:::core
    end

    %% External Layer
    subgraph "External Dependencies"
        style ext_layer fill:#E0E0E0,stroke:#888
        YTDLP["yt-dlp Library"]:::ext
        RequestsLib["requests Library"]:::ext
        FFmpegBin["FFmpeg Binary"]:::ext
        FileSystem[(File System)]:::ext
        YouTubeCloud[(YouTube/Vimeo/HTTP Streams)]:::ext
        GitHubAPI((GitHub Releases API)):::ext
        Network[(Network/Internet)]:::ext
    end

    %% Connections UI -> Core
    EntryPoint -->|"instantiates"| MainWindow
    MainWindow -->|"loads pages"| HomePage
    MainWindow -->|loads| MP4Page
    MainWindow -->|loads| MP3Page
    MainWindow -->|loads| QueuePage
    MainWindow -->|loads| HistoryPage
    MainWindow -->|loads| SchedulerPage
    MainWindow -->|loads| ProfilePage
    MainWindow -->|loads| SettingsPage

    HomePage -->|"Qt Signal/Slot"| Downloader
    MP4Page -->|"calls"| Downloader
    MP3Page -->|"calls"| Downloader
    QueuePage -->|"enqueues"| Downloader
    HistoryPage -->|"queries"| HistoryStore
    SchedulerPage -->|"schedules"| Downloader
    ProfilePage -->|"loads/saves"| ProfileManagerCore
    SettingsPage -->|"triggers"| Updater

    %% Components to Core
    ProfileManagerWidget -->|uses| ProfileManagerCore
    ThemeManager -->|applies| DarkTheme
    ThemeManager -->|applies| LightTheme
    TrayIcon -->|signals| MainWindow
    LogDock -->|displays logs from| Utils

    %% Core -> External
    Downloader -->|"uses yt-dlp"| YTDLP
    Downloader -->|"HTTP requests"| RequestsLib
    Downloader -->|"writes"| FileSystem
    Downloader -->|"network I/O"| Network
    FFmpegChecker -->|"validates"| FFmpegBin
    HistoryStore -->|"I/O"| FileSystem
    ProfileManagerCore -->|"read/write"| FileSystem
    Updater -->|"calls REST"| GitHubAPI
    Updater -->|"writes"| FileSystem

    %% Legend
    subgraph "Legend"
        style legend fill:none,stroke:none
        UI["UI Layer"]:::ui
        CORE["Core Layer"]:::core
        EXT["External"]:::ext
    end

    %% Click Events
    click EntryPoint "https://github.com/efeckc17/youtubego/blob/main/main.py"
    click MainWindow "https://github.com/efeckc17/youtubego/blob/main/ui/main_window.py"
    click HomePage "https://github.com/efeckc17/youtubego/blob/main/ui/pages/home_page.py"
    click MP4Page "https://github.com/efeckc17/youtubego/blob/main/ui/pages/mp4_page.py"
    click MP3Page "https://github.com/efeckc17/youtubego/blob/main/ui/pages/mp3_page.py"
    click QueuePage "https://github.com/efeckc17/youtubego/blob/main/ui/pages/queue_page.py"
    click HistoryPage "https://github.com/efeckc17/youtubego/blob/main/ui/pages/history_page.py"
    click SchedulerPage "https://github.com/efeckc17/youtubego/blob/main/ui/pages/scheduler_page.py"
    click ProfilePage "https://github.com/efeckc17/youtubego/blob/main/ui/pages/profile_page.py"
    click SettingsPage "https://github.com/efeckc17/youtubego/blob/main/ui/pages/settings_page.py"
    click AnimatedButton "https://github.com/efeckc17/youtubego/blob/main/ui/components/animated_button.py"
    click DragDropLineEdit "https://github.com/efeckc17/youtubego/blob/main/ui/components/drag_drop_line_edit.py"
    click LogDock "https://github.com/efeckc17/youtubego/blob/main/ui/components/log_dock.py"
    click MenuBar "https://github.com/efeckc17/youtubego/blob/main/ui/components/menu_bar.py"
    click ProfileManagerWidget "https://github.com/efeckc17/youtubego/blob/main/ui/components/profile_manager.py"
    click SearchPopup "https://github.com/efeckc17/youtubego/blob/main/ui/components/search_popup.py"
    click SearchSystemHelper "https://github.com/efeckc17/youtubego/blob/main/ui/components/search_system.py"
    click ThemeManager "https://github.com/efeckc17/youtubego/blob/main/ui/components/theme_manager.py"
    click TrayIcon "https://github.com/efeckc17/youtubego/blob/main/ui/components/tray_icon.py"
    click ProfileDialog "https://github.com/efeckc17/youtubego/blob/main/ui/dialogs/profile_dialog.py"
    click QueueAddDialog "https://github.com/efeckc17/youtubego/blob/main/ui/dialogs/queue_add_dialog.py"
    click ScheduleAddDialog "https://github.com/efeckc17/youtubego/blob/main/ui/dialogs/schedule_add_dialog.py"
    click SideMenuLayout "https://github.com/efeckc17/youtubego/blob/main/ui/layouts/side_menu.py"
    click TopBarLayout "https://github.com/efeckc17/youtubego/blob/main/ui/layouts/top_bar.py"
    click StatusBarLayout "https://github.com/efeckc17/youtubego/blob/main/ui/layouts/status_bar.py"
    click DarkTheme "https://github.com/efeckc17/youtubego/blob/main/ui/themes/dark.qss"
    click LightTheme "https://github.com/efeckc17/youtubego/blob/main/ui/themes/light.qss"
    click Downloader "https://github.com/efeckc17/youtubego/blob/main/core/downloader.py"
    click FFmpegChecker "https://github.com/efeckc17/youtubego/blob/main/core/ffmpeg_checker.py"
    click HistoryStore "https://github.com/efeckc17/youtubego/blob/main/core/history.py"
    click ProfileManagerCore "https://github.com/efeckc17/youtubego/blob/main/core/profile.py"
    click Updater "https://github.com/efeckc17/youtubego/blob/main/core/updater.py"
    click Utils "https://github.com/efeckc17/youtubego/blob/main/core/utils.py"
    click Version "https://github.com/efeckc17/youtubego/blob/main/core/version.py"

    %% Class Definitions
    classDef ui fill:#D6E9FF,stroke:#2B7CE9,color:#000;
    classDef core fill:#DFFFE0,stroke:#2B8E0D,color:#000;
    classDef ext fill:#E0E0E0,stroke:#888,color:#000;
```
