# jxxghp/moviepilot architecture

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

- Interactive diagram: https://gitdiagram.com/jxxghp/moviepilot
- Repository: https://github.com/jxxghp/moviepilot

## Overview

##### Main Components
- Frontend: Although not included in this repository, note that a separate Vue3-based frontend (MoviePilot-Frontend) interfaces with this backend.
- API Layer: This is clearly represented by the “app/api/” directory with multiple endpoints (login, media, download, dashboard, etc.). It handles HTTP/REST requests and responses.
- Business Logic (Chain): The “app/chain/” directory encapsulates step-by-step business flows, mapping closely to API endpoints. It acts as a mediator to process requests and trigger actions.
- Core Modules: Found in “app/core/”, this contains key components such as configuration management, caching, event handling, plugin management, and metadata extraction. It represents common services used by the entire application.
- Database Layer: All operations related to data persistence are grouped under “app/db/”. It includes database initialization, models (for users, downloads, subscriptions, etc.), and operational scripts. Make sure to include a depiction of how models interact with business logic.
- Helper Utilities: “app/helper/” provides utility functions for common tasks like file downloading, cookie handling, and formatting – these support multiple layers.
- Modules / External Integrations: The “app/modules/” directory is extensive and includes integrations with various external services (e.g., Douban, Bangumi, Emby, Plex, The Movie DB, etc.). This shows that the backend is built for extendability, with each module handling specific integration or functionality.
- Plugins System: Both “app/plugins/” and parts of the “app/core/plugin.py” reveal that the system is designed to be easily extended.
- Startup and Scheduling: “app/startup/” and other files like “app/scheduler.py” indicate that there is an orchestration layer to initialize modules and schedule recurring tasks.
- Utility and Configuration Files: These include environment and configuration files in the “config/” folder, Docker files, and build scripts that are key to deployment and runtime environment setup.

##### Relationships and Interactions
- The Frontend (Vue3) communicates with the FastAPI-based backend through the API endpoints.
- The API layer receives requests from the frontend and routes them to the business logic (chain) layer.
- The Chain layer processes these requests by invoking operations in core services, performing validation, triggering helper functions, and interfacing with external modules.
- Database interactions (CRUD operations) are handled via the “app/db/” layer, with models being used by both the business chain and the API.
- The Plugins and Modules systems interact with both the core and chain layers to extend functionality for specific external services.
- Utility functions in “app/helper/” and “app/utils/” are used across multiple layers to handle common operations like file management, network communications, and security (e.g., encryption or two-factor authentication).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different directories separate API routing, business logic, core services, database operations, integrations, and utilities.
- Modularity: The “app/modules/” and “app/plugins/” directories show a highly modular design for extensibility and maintainability.
- Clean API Design: The FastAPI-based endpoints encapsulated in “app/api/” follow RESTful principles for clear interaction boundaries.
- Dependency Injection & Initialization: The startup scripts (found under “app/startup/”) suggest an initialization phase where various modules and plugins are loaded.
- Containerization: Use of Docker (Dockerfile, .dockerignore) indicates that the project supports containerized deployments.

##### Relevant Technologies, Frameworks, & Libraries
- Backend Framework: FastAPI
- Frontend Technology: Vue3 (separate repository)
- Database: Likely an SQL/ORM based on the structured “models” directories (precise tech not directly specified but indicated by oper and models design)
- External Integrations: Several modules indicate integration with services such as Douban, TMDB, TheTVDB, Plex, Emby, qbittorrent, Transmission, etc.
- Containerization Tools: Docker and related configuration files.
- Workflow & Scheduling Libraries: Evidenced by “app/scheduler.py” and “app/startup/workflow_initializer.py”

- Clear Labels: Each component should be clearly named to reflect its directory (e.g., "app/api (FastAPI Endpoints)", "app/chain (Business Workflows)", "app/db (Database Models & Operations)", "app/modules (External Service Integrations)").
- Detailed Annotations: Include notes on important design principles such as modularity, extensibility with plugins, and how containerization (via Docker) supports deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    F["Frontend (Vue3)"]:::frontend

    API["API Layer (FastAPI Endpoints)"]:::api
    API_EP["API Endpoints"]:::api

    CH["Business Logic (Chain)"]:::chain

    CORE["Core Modules & Services"]:::core
    CORE_META["Core Metadata Extraction"]:::core
    PLUGINS["Plugins System"]:::plugins

    DB["Database Layer (Models & Operations)"]:::db
    DB_MODELS["Database Models"]:::db

    HELPER["Helper Utilities"]:::helper
    UTILS["Utility Functions"]:::helper

    MODULES["External Integrations (Modules)"]:::modules

    STARTUP["Startup & Scheduling"]:::startup
    SCHEDULER["Scheduler Script"]:::startup

    CONFIG["Utility & Configuration Files"]:::config

    %% Relationships
    F -->|"HTTPRequests"| API
    API -->|"definesEndpoints"| API_EP
    API -->|"routesTo"| CH
    CH -->|"invokes"| CORE
    CH -->|"performsCRUD"| DB
    CH -->|"utilizes"| HELPER
    CH -->|"callsIntegration"| MODULES
    CORE -->|"handlesMeta"| CORE_META
    CORE -->|"managesPlugins"| PLUGINS
    DB -->|"includes"| DB_MODELS
    HELPER -->|"uses"| UTILS
    STARTUP -->|"initializes"| API
    STARTUP -->|"initializes"| CH
    STARTUP -->|"initializes"| MODULES
    STARTUP -->|"schedules"| SCHEDULER
    CONFIG -->|"configuresStartup"| STARTUP
    CONFIG -->|"configuresDB"| DB
    CONFIG -->|"configuresCore"| CORE
    CONFIG -->|"configuresHelpers"| HELPER
    CONFIG -->|"configuresPlugins"| PLUGINS
    CONFIG -->|"configuresModules"| MODULES
    CONFIG -->|"providesEnv"| API

    %% Click Events
    click API "https://github.com/jxxghp/moviepilot/tree/v2/app/api/"
    click API_EP "https://github.com/jxxghp/moviepilot/tree/v2/app/api/endpoints/"
    click CH "https://github.com/jxxghp/moviepilot/tree/v2/app/chain/"
    click CORE "https://github.com/jxxghp/moviepilot/tree/v2/app/core/"
    click CORE_META "https://github.com/jxxghp/moviepilot/tree/v2/app/core/meta/"
    click PLUGINS "https://github.com/jxxghp/moviepilot/tree/v2/app/plugins/"
    click DB "https://github.com/jxxghp/moviepilot/tree/v2/app/db/"
    click DB_MODELS "https://github.com/jxxghp/moviepilot/tree/v2/app/db/models/"
    click HELPER "https://github.com/jxxghp/moviepilot/tree/v2/app/helper/"
    click UTILS "https://github.com/jxxghp/moviepilot/tree/v2/app/utils/"
    click MODULES "https://github.com/jxxghp/moviepilot/tree/v2/app/modules/"
    click STARTUP "https://github.com/jxxghp/moviepilot/tree/v2/app/startup/"
    click SCHEDULER "https://github.com/jxxghp/moviepilot/blob/v2/app/scheduler.py"
    click CONFIG "https://github.com/jxxghp/moviepilot/tree/v2/config/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef chain fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef core fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef db fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef helper fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef modules fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef plugins fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef startup fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
