# smartclipai/faceless-video-api architecture

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

- Interactive diagram: https://gitdiagram.com/smartclipai/faceless-video-api
- Repository: https://github.com/smartclipai/faceless-video-api

## Overview

##### Project Type and Purpose
- This is a backend microservice (FastAPI) focused on AI-driven faceless video creation.
- It exposes REST endpoints for authentication, story generation, image creation, and video production.
- It uses asynchronous background processing, a PostgreSQL database, and integrates with external AI/TTS/storage services.

##### File Structure
- app/main.py – FastAPI application entrypoint.
- app/api/endpoints/ – HTTP router layer (`auth.py`, `image.py`, `video.py`).
- app/core/ – configuration, logging, security (JWT).
- app/db/ – SQLAlchemy setup, session management, DB initialization script.
- app/models, app/schemas – ORM models and Pydantic schemas.
- app/services/ – business logic for story, image, audio, video generation, storage, and background task processing.
- app/utils, app/resources – helper functions, fonts, transitions.
- config.json – feature toggles and AI/TTS parameters.
- scripts/run_init_db.py – database bootstrap.
- requirements.txt, .env.example – dependencies and environment variables.

##### README for Insights
- RESTful API with token auth (OAuth2PasswordBearer).
- Async background tasks for long-running video builds.
- Uses OpenAI (or Azure) for story, FAL or Replicate for image AI, TTS voices for narration, and Cloudflare R2 for storage.
- PostgreSQL for persistence; uvicorn as the server.

##### Main Components
A. API Layer
- Uvicorn + FastAPI (app/main.py)
- Endpoint Routers (/v1/auth, /v1/image, /v1/video)
- Security middleware (JWT auth)
B. Service Layer
- StoryGenerator (calls OpenAI)
- ImageGenerator / ImageAPI (calls FAL/Replicate)
- AudioGenerator (TTS engine)
- VideoGenerator (stitch images+audio, add subtitles)
- VideoTaskProcessor (async job orchestration)
- StorageService (uploads to Cloudflare R2)
C. Data Layer
- PostgreSQL (user, image, video_task tables) via SQLAlchemy
- Pydantic schemas for request/response validation
D. External Dependencies
- OpenAI / Azure OpenAI endpoint
- FAL API or Replicate API
- Text-to-Speech engine or API
- Cloudflare R2 storage
E. Configuration
- config.json feature toggles
- .env (API keys, DB URL, JWT secret)

##### Relationships and Data Flows
1. Client → FastAPI Endpoints (HTTP POST)
2. Auth endpoint ↔ PostgreSQL (validate credentials, issue JWT)
3. Video/Image endpoints → VideoTaskProcessor (enqueue background job)
4. VideoTaskProcessor orchestrates:
a. StoryGenerator → OpenAI → returns text scenes
b. For each scene: ImageGenerator → FAL/Replicate → returns images
c. AudioGenerator → TTS API → returns audio files
d. VideoGenerator → merges images+audio → produces final video file
5. StorageService → Cloudflare R2 → returns public URL
6. VideoTaskProcessor updates PostgreSQL with progress & result URL
7. Client polls status endpoint → reads from PostgreSQL → retrieves final URL

##### Architectural Patterns & Principles
- Layered architecture: Router → Service → Data
- Dependency injection using FastAPI’s Depends
- Asynchronous background processing (non-blocking API)
- Externalized configuration (config.json + env)
- Separation of concerns: authentication, business logic, persistence, external integration

##### Essential Elements
- Component names & boundaries
- Annotations for key technologies (FastAPI, SQLAlchemy, Pydantic, Uvicorn, PostgreSQL, Cloudflare R2, OpenAI, FAL/Replicate, TTS)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Tier
    subgraph "API Tier"
        A_main["Uvicorn + FastAPI"]:::internal
        authR["Auth Router\n/v1/auth"]:::internal
        imgR["Image Router\n/v1/image"]:::internal
        vidR["Video Router\n/v1/video"]:::internal
        sec["Security Middleware\n(JWT/OAuth2)"]:::internal
        configCode["Config & Logging"]:::internal
    end

    %% Business Logic Tier
    subgraph "Business Logic Tier"
        story["StoryGenerator"]:::internal
        imgGen["ImageGenerator"]:::internal
        imgAPI["Image API Wrapper"]:::internal
        audio["AudioGenerator"]:::internal
        videoGen["VideoGenerator"]:::internal
        taskProc["VideoTaskProcessor"]:::internal
        storage["StorageService"]:::internal
    end

    %% Persistence Tier
    subgraph "Persistence Tier"
        db["PostgreSQL\n(user,image,video_task tables)"]:::db
        models["ORM Models"]:::internal
        session["DB Session & Init"]:::internal
        schemas["Pydantic Schemas"]:::internal
    end

    %% External Services Tier
    subgraph "External Services Tier"
        openai["OpenAI/Azure OpenAI"]:::external
        fal["FAL / Replicate"]:::external
        tts["TTS Engine/API"]:::external
        r2["Cloudflare R2"]:::external
    end

    document["Configuration Files\nconfig.json\n.env.example"]:::document
    client["Client"]:::external

    %% Flows
    client -->|1 POST| A_main
    A_main --> authR
    A_main --> imgR
    A_main --> vidR
    authR -->|2 Validate| db
    authR --> models
    authR --> schemas
    imgR --> sec
    vidR --> sec
    imgR -->|3 Enqueue| taskProc
    vidR -->|3 Enqueue| taskProc
    taskProc -->|4a Generate Story| story
    story --> openai
    taskProc -->|4b Generate Image| imgGen
    imgGen --> imgAPI
    imgAPI --> fal
    taskProc -->|4c Generate Audio| audio
    audio --> tts
    taskProc -->|4d Generate Video| videoGen
    videoGen --> storage
    storage --> r2
    taskProc -->|6 Update| db
    videoGen -->|6 Update| db
    client -->|7 Poll Status| vidR

    session --> db
    models --> session
    schemas --> session
    document --> A_main
    document --> story
    document --> imgGen
    document --> audio
    document --> videoGen
    document --> taskProc

    %% Click Events
    click A_main "https://github.com/smartclipai/faceless-video-api/blob/main/app/main.py"
    click authR "https://github.com/smartclipai/faceless-video-api/blob/main/app/api/endpoints/auth.py"
    click imgR "https://github.com/smartclipai/faceless-video-api/blob/main/app/api/endpoints/image.py"
    click vidR "https://github.com/smartclipai/faceless-video-api/blob/main/app/api/endpoints/video.py"
    click sec "https://github.com/smartclipai/faceless-video-api/blob/main/app/core/security.py"
    click configCode "https://github.com/smartclipai/faceless-video-api/blob/main/app/core/config.py"
    click configCode "https://github.com/smartclipai/faceless-video-api/blob/main/app/core/logging.py"
    click story "https://github.com/smartclipai/faceless-video-api/blob/main/app/services/story_generator.py"
    click imgGen "https://github.com/smartclipai/faceless-video-api/blob/main/app/services/image_generator.py"
    click imgAPI "https://github.com/smartclipai/faceless-video-api/blob/main/app/services/image_api.py"
    click audio "https://github.com/smartclipai/faceless-video-api/blob/main/app/services/audio_generator.py"
    click videoGen "https://github.com/smartclipai/faceless-video-api/blob/main/app/services/video_generator.py"
    click taskProc "https://github.com/smartclipai/faceless-video-api/blob/main/app/services/video_task_processor.py"
    click storage "https://github.com/smartclipai/faceless-video-api/blob/main/app/services/storage.py"
    click models "https://github.com/smartclipai/faceless-video-api/tree/main/app/models"
    click session "https://github.com/smartclipai/faceless-video-api/tree/main/app/db"
    click schemas "https://github.com/smartclipai/faceless-video-api/tree/main/app/schemas"
    click document "https://github.com/smartclipai/faceless-video-api/blob/main/config.json"
    click document "https://github.com/smartclipai/faceless-video-api/blob/main/.env.example"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366d6,color:#000;
    classDef external fill:#E6FFEA,stroke:#28A745,color:#000;
    classDef db fill:#FFF5BA,stroke:#CC9C00,color:#000;
    classDef document fill:#FFEFEF,stroke:#D73A49,color:#000;
```
