# rayventura/shortgpt architecture

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

- Interactive diagram: https://gitdiagram.com/rayventura/shortgpt
- Repository: https://github.com/rayventura/shortgpt

## Overview

##### Project Type and Purpose
- ShortGPT is an AI-driven video automation framework written in Python.
- It is primarily a backend framework (engines, editing framework, utilities), bundled with a simple Gradio-based GUI and CLI entry points (runShortGPT.py).
- Its purpose is to automate the entire pipeline of short-form video creation, translation, voiceover, captioning, asset sourcing, and editing by orchestrating LLM calls, media APIs, and video editing libraries.

##### High-Level File Structure Analysis
- Top-level folders:
– gui: Gradio UI and abstract UI components
– shortGPT: core code (subpackages: api_utils, audio, config, database, editing_framework, editing_utils, engine, gpt, prompt_templates, tracking, utils)
– docs: Docusaurus docs site
– public/assets/videos: static/demo assets
- Entry points: runShortGPT.py / runShortGPTColab.py for launching the web UI; setup.py for packaging; Dockerfile + README-Docker.md for containerized deployment.
- Config & persistence: shortGPT/config for app settings, shortGPT/database using TinyDB (template_asset_db.json); .env for secrets; requirements.txt for dependencies.

##### Key Components and Interactions
- UI Layer
– Gradio Web App (gui/gui_gradio.py) and CLI (shortGPT/utils/cli.py)
– Exposes endpoints/buttons for selecting engine (Short, Video, Translation) and parameters.
- Controller/Runner
– runShortGPT.py loads config, initializes the chosen Engine class (ContentShortEngine, ContentVideoEngine, ContentTranslationEngine).
- Engine Layer
– Each Engine orchestrates:
· Prompt generation (shortGPT/gpt)
· Asset sourcing (shortGPT/api_utils: Pexels, Bing Image; shortGPT/audio)
· Editing pipeline (shortGPT/editing_framework: editing_steps JSON + core_editing_engine)
· Rendering (MoviePy)
· Persistence/tracking (shortGPT/tracking, database)
- Core Services / Libraries
– GPT modules: OpenAI LLM calls
– Voice synthesis: ElevenLabs API, EdgeTTS
– Video editing: MoviePy via editing framework
– TinyDB for storing intermediate state/asset info
- External Services
– OpenAI, ElevenLabs, EdgeTTS, Pexels API, Bing Image Search

##### Architectural Patterns and Design Principles
- Layered modular monolith: clear separation of UI, orchestration (engines), domain logic (editing framework, GPT utils), persistence, and external API adapters.
- Plug-in style editing framework: JSON-defined editing steps and flows allow adding or modifying operations without code changes.
- Dependency injection via config (shortGPT/config/config.py) and environment variables.
- Single process, synchronous orchestration—no microservices, but could evolve to microservices by breaking out engine groups.

- Editing framework’s JSON flows as a subcomponent under Core Logic.
- Role of shortGPT/gpt and shortGPT/api_utils as adapters to AI and media services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        GUI["Gradio Web App"]:::ui
        CLI["CLI (argparse)"]:::ui
    end

    %% Runner / Controller
    subgraph "Runner / Controller" 
        direction TB
        Runner["runShortGPT.py (Python script)"]:::runner
        ColabRunner["runShortGPTColab.py"]:::runner
    end

    %% Engine Layer
    subgraph "Engine Layer" 
        direction TB
        AbstractEngine["AbstractContentEngine"]:::engine
        ShortEngine["ContentShortEngine"]:::engine
        VideoEngine["ContentVideoEngine"]:::engine
        TransEngine["ContentTranslationEngine"]:::engine
        SubEngines["Additional Engines"]:::engine
    end

    %% Core Logic
    subgraph "Core Logic" 
        direction TB
        subgraph "Editing Framework" 
            direction TB
            CoreEdit["core_editing_engine"]:::core
            EditIF["editing_engine interface"]:::core
            JSONSteps["editing_steps (*.json)"]:::core
            Flows["flows (*.json)"]:::core
            Logger["rendering_logger"]:::core
        end
    end

    %% Adapter Layers
    subgraph "Adapters" 
        direction TB
        GPTAdapter["GPT Adapter Layer"]:::adapter
        APIAdapter["API Adapter Layer"]:::adapter
        AudioAdapter["Audio Adapter Layer"]:::adapter
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DB["TinyDB (content_database)"]:::persistence
        TemplateDB["template_asset_db.json"]:::persistence
        Tracking["Tracking & Analytics"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI"]:::external
        ElevenLabs["ElevenLabs API"]:::external
        EdgeTTS["EdgeTTS"]:::external
        Pexels["Pexels API"]:::external
        Bing["Bing Image Search"]:::external
    end

    %% Connections
    GUI -->|select parameters| Runner
    CLI -->|select parameters| Runner
    Runner -->|"initialize engine"| AbstractEngine
    AbstractEngine -->|uses| ShortEngine
    AbstractEngine -->|uses| VideoEngine
    AbstractEngine -->|uses| TransEngine
    AbstractEngine -->|may use| SubEngines

    ShortEngine -->|"generate_prompt()"| GPTAdapter
    VideoEngine -->|"generate_prompt()"| GPTAdapter
    TransEngine -->|"generate_prompt()"| GPTAdapter

    GPTAdapter -->|calls LLM| OpenAI

    ShortEngine -->|"fetch assets"| APIAdapter
    VideoEngine -->|"fetch assets"| APIAdapter
    SubEngines -->|"fetch assets"| APIAdapter

    APIAdapter -->|call media APIs| Pexels
    APIAdapter -->|call media APIs| Bing

    ShortEngine -->|"get_voice()"| AudioAdapter
    VideoEngine -->|"get_voice()"| AudioAdapter

    AudioAdapter -->|synthesize| ElevenLabs
    AudioAdapter -->|synthesize| EdgeTTS

    ShortEngine -->|"run editing pipeline"| CoreEdit
    VideoEngine -->|"run editing pipeline"| CoreEdit
    TransEngine -->|"run editing pipeline"| CoreEdit

    CoreEdit -->|"load steps"| JSONSteps
    CoreEdit -->|"load flows"| Flows
    CoreEdit -->|"log rendering"| Logger
    CoreEdit -->|"render_video()"| ExternalMoviePy[("MoviePy")]:::core

    ShortEngine -->|"persist state"| DB
    VideoEngine -->|"persist state"| DB
    TransEngine -->|"persist state"| DB

    DB -->|template| TemplateDB
    ShortEngine -->|"track usage"| Tracking
    VideoEngine -->|"track usage"| Tracking

    %% Click Events
    click GUI "https://github.com/rayventura/shortgpt/blob/stable/gui/gui_gradio.py"
    click CLI "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/utils/cli.py"
    click Runner "https://github.com/rayventura/shortgpt/blob/stable/runShortGPT.py"
    click ColabRunner "https://github.com/rayventura/shortgpt/blob/stable/runShortGPTColab.py"
    click AbstractEngine "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/engine/abstract_content_engine.py"
    click ShortEngine "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/engine/content_short_engine.py"
    click VideoEngine "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/engine/content_video_engine.py"
    click TransEngine "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/engine/content_translation_engine.py"
    click SubEngines "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/engine/facts_short_engine.py"
    click CoreEdit "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/editing_framework/core_editing_engine.py"
    click EditIF "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/editing_framework/editing_engine.py"
    click JSONSteps "https://github.com/rayventura/shortgpt/tree/stable/shortGPT/editing_framework/editing_steps/"
    click Flows "https://github.com/rayventura/shortgpt/tree/stable/shortGPT/editing_framework/flows/"
    click Logger "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/editing_framework/rendering_logger.py"
    click GPTAdapter "https://github.com/rayventura/shortgpt/tree/stable/shortGPT/gpt/"
    click APIAdapter "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/api_utils/pexels_api.py"
    click AudioAdapter "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/audio/edge_voice_module.py"
    click DB "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/database/content_database.py"
    click TemplateDB "https://github.com/rayventura/shortgpt/blob/stable/.database/template_asset_db.json"
    click Tracking "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/tracking/api_tracking.py"
    click Config "https://github.com/rayventura/shortgpt/blob/stable/shortGPT/config/config.py"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#000,stroke-width:1px
    classDef runner fill:#d9ead3,stroke:#000,stroke-width:1px
    classDef engine fill:#d0e0e3,stroke:#000,stroke-width:1px
    classDef core fill:#f9cb9c,stroke:#000,stroke-width:1px
    classDef adapter fill:#ffe599,stroke:#000,stroke-width:1px
    classDef persistence fill:#d5a6bd,stroke:#000,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#000,stroke-width:1px
```
