# gabriellaxy/tiktokaivideogenerator architecture

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

- Interactive diagram: https://gitdiagram.com/gabriellaxy/tiktokaivideogenerator
- Repository: https://github.com/gabriellaxy/tiktokaivideogenerator

## Overview

##### Project Type and Purpose
- This is a content‐generation pipeline tool written in Python. It orchestrates AI services to produce short vertical videos (1080×1920) with script, images, audio, captions, and final video composition—optimized for TikTok, Reels, and Shorts.

##### Top‐Level Components
a. **CLI/Input Layer**
- `main.py` + `config.json` + `run.bat`
- Gathers user inputs: project folder, topic, style, audience, CTA.
- Reads API keys from `config.json`.
b. **Orchestration Layer (utils/\*.py)**
- `script_generator.py`: Calls Groq Cloud API (Llama3) → `script.json`
- `image_prompt_generator.py`: Transforms script → `image_prompts.json`
- `image_generator.py`: Calls Together AI FLUX-1 → stores images in `images/`
- `audio_generator.py`: Generates TTS via Kokoro or Edge → `audio/voiceover.mp3`
- `caption_generator.py`: Uses Whisper → `captions/captions.json`
- `caption_overlay.py`: Styles and overlays captions
- `video_composer.py`: Uses MoviePy + FFmpeg + ImageMagick → final video(s)
c. **Artifacts & Storage**
- JSON docs (`script.json`, `image_prompts.json`, `captions.json`)
- Folders: `images/`, `audio/`, `captions/`
- Final video outputs: `final_video.mp4`, `final_video_with_captions.mp4`
d. **External Services**
- Groq Cloud API (Script)
- Together AI FLUX-1 API (Images)
- Kokoro TTS / Edge TTS (Audio)
- OpenAI Whisper (Captions)
- FFmpeg & ImageMagick (Media processing)

##### Data Flows & Interactions
- User → `main.py` → loads config → invokes utils in sequence
- `script_generator` → JSON script → passed to prompt generator
- `image_prompt_generator` → image prompts JSON → passed to image generator
- `image_generator` → image files → passed to composer
- `audio_generator` → MP3 → passed to caption_generator & composer
- `caption_generator` → captions JSON → passed to caption_overlay & composer
- `video_composer` + `caption_overlay` → final MP4(s)

##### Architectural Patterns & Design Principles
- **Pipeline / Chain of Responsibility**: Each util module performs one job, passes output to the next.
- **Modularity & Separation of Concerns**: Script, prompt, image, audio, caption, composition all isolated.
- **Config‐Driven**: `config.json` centralizes API keys.
- **Layered Approach**: Input → Processing → Storage → Composition → Output.

- Clear labels on every block (e.g., “ScriptGenerator (Groq API)”).
- Annotations for important config or fallback logic (e.g., “if Kokoro fails → use Edge TTS”).

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI/Input Layer
    subgraph "CLI/Input Layer"
        CLI["main.py"]:::internal
        CFG["config.json"]:::data
        RUN["run.bat"]:::internal
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer (utils/*.py)"
        SG["Script Generator\n(Groq API)"]:::internal
        IPG["Image Prompt Generator"]:::internal
        IG["Image Generator\n(FLUX-1)"]:::internal
        AG["Audio Generator\n(Kokoro/Edge TTS)"]:::internal
        CG["Caption Generator\n(Whisper)"]:::internal
        CO["Caption Overlay"]:::internal
        VC["Video Composer\n(MoviePy, FFmpeg,\nImageMagick)"]:::internal
    end

    %% Artifacts & Storage
    subgraph "Artifacts & Storage"
        SJ["script.json"]:::data
        IPJ["image_prompts.json"]:::data
        IMG["images/"]:::data
        AV["audio/voiceover.mp3"]:::data
        CJ["captions.json"]:::data
        CAPF["captions/"]:::data
        FONT["EastmanRomanTrial-Black.otf"]:::data
        FV["final_video.mp4"]:::data
        FVC["final_video_with_captions.mp4"]:::data
    end

    %% External Services
    subgraph "External Services"
        GC["Groq Cloud API"]:::external
        TA["Together AI FLUX-1"]:::external
        KT["Kokoro TTS"]:::external
        ET["Edge TTS"]:::external
        OW["OpenAI Whisper"]:::external
        FF["FFmpeg & ImageMagick"]:::external
    end

    %% Data Flows
    CLI -->|"reads"| CFG
    CLI --> SG
    SG -->|"script.json"| SJ
    SG --> GC
    SJ --> IPG
    IPG -->|"image_prompts.json"| IPJ
    IPG --> SG
    IPJ --> IG
    IG --> IMG
    IG --> TA
    IMG --> VC
    CLI --> AG
    AG --> AV
    AG --> KT
    AG --> ET
    AV --> CG
    AV --> VC
    CG -->|"captions.json"| CJ
    CG --> OW
    CJ --> CO
    CO --> CAPF
    CO --> VC
    VC -->|"final_video.mp4"| FV
    VC -->|"final_video_with_captions.mp4"| FVC
    VC --> FF

    %% Click Events
    click CLI "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/main.py"
    click CFG "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/config.json"
    click RUN "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/run.bat"
    click SG "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/utils/script_generator.py"
    click IPG "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/utils/image_prompt_generator.py"
    click IG "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/utils/image_generator.py"
    click AG "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/utils/audio_generator.py"
    click CG "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/utils/caption_generator.py"
    click CO "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/utils/caption_overlay.py"
    click VC "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/utils/video_composer.py"
    click FONT "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/assets/fonts/EastmanRomanTrial-Black.otf"
    click FVC "https://github.com/gabriellaxy/tiktokaivideogenerator/blob/main/.github/final_video_with_captions.mp4"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef data fill:#ABEBC6,stroke:#1D8348,color:#1B2631;
    classDef external fill:#F5B041,stroke:#B9770E,color:#1B2631;
```
