# greywarden07/faceforge architecture

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

- Interactive diagram: https://gitdiagram.com/greywarden07/faceforge
- Repository: https://github.com/greywarden07/faceforge

## Overview

##### Project Type & Purpose
- Project type: Desktop/CLI AI application (not a web service)
- Purpose: Real-time face swapping & enhancement using deep-learning models, via both CLI and CustomTkinter GUI

##### Top-Level Architecture Overview
- Entry points
– run.py (main orchestrator)
– run-cuda.bat / run-directml.bat (Windows launcher scripts)
- User Interfaces
– CLI interface (argument parser in run.py)
– GUI interface (modules/ui.py + modules/ui.json + CustomTkinter)
- Core Orchestration
– modules/core.py (pipeline setup & coordination)
– modules/globals.py (config & state)
- AI & CV Processing
– Face Detection & Clustering
- modules/face_analyser.py (InsightFace & OpenCV)
- modules/cluster_analysis.py
– NSFW Filtering
- modules/predicter.py (OpenNSFW2)
– Frame Processing Pipeline (plugin-style)
- modules/processors/frame/core.py (pipeline engine)
- modules/processors/frame/face_swapper.py (ONNX InSwap)
- modules/processors/frame/face_enhancer.py (GFPGAN)
- Video/Capture & I/O
– modules/video_capture.py (webcam/live)
– modules/capturer.py (file I/O, frames extraction)
– Encoding & Audio Handling (OpenCV + FFmpeg via wrappers)
- Model Storage
– models/ directory (pretrained ONNX/PyTorch model files)

##### Relationships & Interactions
- User → run.py
– CLI flags or GUI events
- run.py → Core
– initializes modules/globals → loads model artifacts → builds processing pipeline
- Core → Video/Capturer
– reads frames from file or camera
- For each frame:
- Core → Encoder/Writer
– writes processed frames to video file (preserving audio if requested) or shows real-time preview
- GUI ↔ Core
– user config changes → pipeline rebuilt on-the-fly → live preview updated

##### Architectural Patterns & Principles
- Pipeline / Plugin Pattern
– Frame processors registered dynamically (see modules/processors/frame)
- Modular Separation of Concerns
– UI, Core, Analytics, Processing modules decoupled via well-defined interfaces
- Configuration & Dependency Injection
– globals.py holds runtime options → passed into modules at init
- Concurrency
– Multi-threaded frame capture vs. processing queues (for real-time performance)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry Points"
        CLI["CLI (run.py)"]:::blue
        CUDA["CUDA Launcher (run-cuda.bat)"]:::purple
        DML["DirectML Launcher (run-directml.bat)"]:::purple
    end

    subgraph "UI Layer"
        CLI
        GUI["GUI (CustomTkinter)"]:::blue
    end

    CORE["Core Orchestrator"]:::green
    GLOBALS["Global Config & State"]:::green
    MODELS["Model Storage (models/)"]:::gray

    subgraph "I/O"
        CAP["File Capturer"]:::green
        VID_CAP["Video Capture (webcam/live)"]:::green
    end

    subgraph "AI/CV Processing"
        FaceAnalysis["Face Detection & Analysis"]:::orange
        Cluster["Clustering Analysis"]:::orange
        Pred["NSFW Predicter"]:::orange
        subgraph "Frame Processing Pipeline"
            PIPE["Pipeline Engine"]:::orange
            Swap["FaceSwap (ONNX InSwap)"]:::orange
            Enhance["FaceEnhancer (GFPGAN)"]:::orange
        end
    end

    ENC["Video Encoder & Writer"]:::green
    PP["Live Preview (GUI Canvas)"]:::blue
    OUT["Output File + Audio"]:::gray

    GPU["GPU (CUDA / DirectML / CPU)"]:::purple

    CLI -->|flags| CORE
    GUI -->|events| CORE
    CUDA --> CORE
    DML --> CORE
    CORE --> GLOBALS
    CORE --> MODELS
    GPU -.->|exec provider| CORE
    CORE --> CAP
    CORE --> VID_CAP
    VID_CAP --> FaceAnalysis
    CAP --> FaceAnalysis
    FaceAnalysis --> Cluster
    Cluster --> Pred
    Pred --> PIPE
    PIPE --> Swap
    PIPE --> Enhance
    Enhance --> ENC
    PIPE --> PP
    CORE --> ENC
    ENC --> OUT
    PP --> GUI

    click CLI "https://github.com/greywarden07/faceforge/blob/main/run.py"
    click CUDA "https://github.com/greywarden07/faceforge/blob/main/run-cuda.bat"
    click DML "https://github.com/greywarden07/faceforge/blob/main/run-directml.bat"
    click GUI "https://github.com/greywarden07/faceforge/blob/main/modules/ui.py"
    click GUI "https://github.com/greywarden07/faceforge/blob/main/modules/ui.json"
    click CORE "https://github.com/greywarden07/faceforge/blob/main/modules/core.py"
    click GLOBALS "https://github.com/greywarden07/faceforge/blob/main/modules/globals.py"
    click FaceAnalysis "https://github.com/greywarden07/faceforge/blob/main/modules/face_analyser.py"
    click Cluster "https://github.com/greywarden07/faceforge/blob/main/modules/cluster_analysis.py"
    click Pred "https://github.com/greywarden07/faceforge/blob/main/modules/predicter.py"
    click PIPE "https://github.com/greywarden07/faceforge/blob/main/modules/processors/frame/core.py"
    click Swap "https://github.com/greywarden07/faceforge/blob/main/modules/processors/frame/face_swapper.py"
    click Enhance "https://github.com/greywarden07/faceforge/blob/main/modules/processors/frame/face_enhancer.py"
    click VID_CAP "https://github.com/greywarden07/faceforge/blob/main/modules/video_capture.py"
    click CAP "https://github.com/greywarden07/faceforge/blob/main/modules/capturer.py"
    click MODELS "https://github.com/greywarden07/faceforge/tree/main/models/"

    classDef blue fill:#ADD8E6,stroke:#000
    classDef green fill:#90EE90,stroke:#000
    classDef orange fill:#FFA500,stroke:#000
    classDef gray fill:#D3D3D3,stroke:#000
    classDef purple fill:#DDA0DD,stroke:#000
```
