# popcorn-official/popcorn-desktop architecture

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

- Interactive diagram: https://gitdiagram.com/popcorn-official/popcorn-desktop
- Repository: https://github.com/popcorn-official/popcorn-desktop

## Overview

##### Project Type and Purpose
- The README and file tree clearly indicate that this is a multi-platform desktop application (available for Windows, macOS, and Linux).
- Its purpose is to stream media content by leveraging BitTorrent protocols, integrating a media player, and offering features like subtitle support, external device control (e.g., AirPlay, Chromecast, DLNA), and language localization.
- The project is built using a web technology stack (see HTML, JavaScript, Stylus, and templating files) and is assembled through Node-based tooling (with package.json, gulpfile.js, yarn scripts) to produce OS-specific distributions.

##### Main Components
a. User Interface Layer:
- Components:
- src/app/index.html (the main entry point)
- Views (src/app/lib/views/) for individual UI pages (movie details, list views, notifications, player, settings, etc.)
- Templates (src/app/templates/) used for rendering these views.
- Stylus/CSS (src/app/styl/) which define themes and UI styles.
- Language support files under src/app/language/ that serve dynamic localization.
- Directional flows from user actions to view updates.

b. Application Core / Business Logic:
- Bootstrap and Main Application: Files like src/app/bootstrap.js and src/app/app.js initialize the application.
- Configuration: src/app/config.js which defines application settings.
- Database Module: src/app/database.js handling data persistence or local state.
- Error handling and notifications via src/app/global.js and src/app/lib/views/notification.js.
- The "updater.js" that may manage version control or application updates.

c. Media, Torrent, and Streaming Subsystems:
- Streaming Module: src/app/streamer.js, which likely orchestrates media streaming logic.
- File Server: src/app/fileserver.js responsible for serving local files or media content over HTTP.
- Integration with external protocols: For example, the butter-provider directory (src/app/butter-provider/) with specialized scripts (anime.js, movie.js, tv.js, yts.js) for interfacing with various content providers.
- Providers: src/app/lib/providers/ (including modules for favorites, torrents, subtitles via src/app/lib/subtitle/ and others) which abstract external API integrations and content retrieval.

d. External Device and Display Integration:
- Device Modules from src/app/lib/device/ (e.g., airplay.js, chromecast.js, dlna.js, xbmc.js) represent connectivity to external playback devices.
- These modules may interact with the streaming engine to allow playback on external screens.

e. Build, Distribution, and Deployment:
- The dist folder contains OS-specific build artifacts (Linux packages, macOS DMG builders, Windows installer scripts).
- Scripts like make_popcorn.sh and files under Create-Desktop-Entry are used for packaging and desktop integration.
- The GitHub workflows (.github/workflows/build.yml) and related config files (e.g., .gitignore, .jshintrc) manage continuous integration and code standards.

##### Architectural Patterns and Component Interactions
- Separation of concerns: The system isolates the UI rendering (views/templates/stylus) from the underlying logic (bootstrap, database, streamer) and from external services (butter-provider, device integrations, subtitle server).
- Data Flow: The UI sends user events which trigger calls to the backend application logic (bootstrap.js, config.js) which then communicates with the file server, database, and streaming modules. For external interactions, providers are used to fetch content and device modules handle casting to external players.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI_Index("Main Entry (index.html)"):::UI
        UI_Views("Views"):::UI
        UI_Templates("Templates"):::UI
        UI_Stylus("Stylus/CSS"):::UI
        UI_Language("Localization Files"):::UI
    end

    %% Application Core / Business Logic
    subgraph "Application Core / Business Logic"
        Core_Bootstrap("Bootstrap & Main App"):::Core
        Core_Config("Configuration"):::Core
        Core_Database("Database Module"):::Core
        Core_Global("Global Error & Notifications"):::Core
        Core_Updater("Updater"):::Core
    end

    %% Media, Torrent, and Streaming Subsystems
    subgraph "Media, Torrent, and Streaming Subsystems"
        Media_Streaming("Streaming Module"):::Media
        Media_FileServer("File Server"):::Media
        Media_Butter("Butter Providers"):::Media
        Media_Providers("Content Providers & Subtitles"):::Media
    end

    %% External Device Integration
    subgraph "External Device Integration"
        Device_Modules("Device Modules"):::Device
    end

    %% Build, Distribution, and Deployment
    subgraph "Build, Distribution, and Deployment"
        Build_Scripts("Build Scripts"):::Build
        Build_Distribution("Distribution Artifacts"):::Build
        Build_Desktop("Desktop Integration"):::Build
        Build_CICD("CI/CD Workflows"):::Build
    end

    %% Data Flow between Components
    UI_Index -->|"userAction"| Core_Bootstrap
    UI_Views -->|"displayUpdate"| Core_Global
    Core_Bootstrap -->|"initStream"| Media_Streaming
    Core_Bootstrap -->|"fileQuery"| Media_FileServer
    Core_Bootstrap -->|"castRequest"| Device_Modules
    %% Build Process Flow
    UI_Index -->|"build"| Build_Scripts
    Core_Bootstrap -->|"build"| Build_Scripts
    Media_Streaming -->|"build"| Build_Scripts
    Device_Modules -->|"build"| Build_Scripts
    Build_Scripts -->|"package"| Build_Distribution
    Build_Distribution -->|"integrateDesktop"| Build_Desktop
    Build_CICD -->|"triggerBuild"| Build_Scripts

    %% Click Events for User Interface Layer
    click UI_Index "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/index.html"
    click UI_Views "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/lib/views/"
    click UI_Templates "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/templates/"
    click UI_Stylus "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/styl/"
    click UI_Language "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/language/"

    %% Click Events for Application Core / Business Logic
    click Core_Bootstrap "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/bootstrap.js"
    click Core_Bootstrap "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/app.js"
    click Core_Config "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/config.js"
    click Core_Database "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/database.js"
    click Core_Global "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/global.js"
    click Core_Global "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/lib/views/notification.js"
    click Core_Updater "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/updater.js"

    %% Click Events for Media, Torrent, and Streaming Subsystems
    click Media_Streaming "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/streamer.js"
    click Media_FileServer "https://github.com/popcorn-official/popcorn-desktop/blob/development/src/app/fileserver.js"
    click Media_Butter "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/butter-provider/"
    click Media_Providers "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/lib/providers/"
    click Media_Providers "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/lib/subtitle/"

    %% Click Event for External Device Integration
    click Device_Modules "https://github.com/popcorn-official/popcorn-desktop/tree/development/src/app/lib/device/"

    %% Click Events for Build, Distribution, and Deployment
    click Build_Scripts "https://github.com/popcorn-official/popcorn-desktop/blob/development/gulpfile.js"
    click Build_Scripts "https://github.com/popcorn-official/popcorn-desktop/blob/development/make_popcorn.sh"
    click Build_Distribution "https://github.com/popcorn-official/popcorn-desktop/tree/development/dist/"
    click Build_Desktop "https://github.com/popcorn-official/popcorn-desktop/tree/development/Create-Desktop-Entry"
    click Build_CICD "https://github.com/popcorn-official/popcorn-desktop/blob/development/.github/workflows/build.yml"
    click Build_CICD "https://github.com/popcorn-official/popcorn-desktop/blob/development/.jshintrc"
    click Build_CICD "https://github.com/popcorn-official/popcorn-desktop/blob/development/.gitignore"

    %% Styles for Component Classes
    classDef UI fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef Core fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef Media fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef Device fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef Build fill:#E6CCFF,stroke:#333,stroke-width:2px;
```
