# jacky-xbb/faceless-video-api architecture

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

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

## Overview

##### Project Type and Purpose
- This is a backend API service (FastAPI) for automated, AI-powered faceless video creation.
- It exposes REST endpoints for authentication, story generation, image creation, and video compilation.
- It leverages external AI services (OpenAI/Azure, FAL, Replicate), a PostgreSQL database, and Cloudflare R2 for asset storage.

##### File Structure
- **app/api**: FastAPI routers & endpoints (auth.py, image.py, video.py)
- **app/core**: Configuration, logging, security utilities
- **app/db**: SQLAlchemy setup (base classes, session, init script)
- **app/models**: ORM models (User, Image, Video, VideoTask)
- **app/schemas**: Pydantic schemas for request/response validation
- **app/services**: Business-logic layers – story_generator, image_generator, video_generator, audio_generator, storage, video_task_processor, image_api
- **app/utils**: Helper functions (image processing, transitions, etc.)
- **app/scripts**: Database initialization script
- **config.json**: Feature toggles & model parameters
- **resources/fonts** & **assets**: Static assets & font files
- **requirements.txt**, **.env.example**, **log_conf.yaml**: Environment & deployment configuration

##### README for Architecture Insights
- RESTful API with Token-based authentication (OAuth2PasswordBearer)
- Async background processing for long-running tasks (video compilation)
- Progress tracking via polling endpoints (VideoTask entities)
- External integrations: OpenAI/Azure OpenAI, FAL flux (schnell/dev), Replicate, Cloudflare R2

##### Key Components
a. **Clients**
- Web or CLI clients consuming the API (Swagger UI, Postman, custom frontends)
b. **API Layer**
- FastAPI server (app/main.py)
- Routers: /v1/auth, /v1/image, /v1/video
- Dependency injection (config, security)
c. **Authentication Service**
- OAuth2PasswordBearer
- JWT token issuance & validation (app/core/security.py)
d. **Business Logic Services**
- StoryGenerator: calls OpenAI to create story text
- ImageAPI/ImageGenerator: calls FAL or Replicate to generate scene images
- AudioGenerator (TTS): creates audio narration
- VideoGenerator: compiles images + audio + subtitles into video
- VideoTaskProcessor: orchestrates background task workflow
- StorageService: uploads/fetches blobs from Cloudflare R2
e. **Database**
- PostgreSQL
- SQLAlchemy models & session (User, Image, Video, VideoTask)
f. **Background Task Queue**
- FastAPI’s BackgroundTasks or an external queue (represented logically)
g. **External AI Services**
- OpenAI / Azure OpenAI (story text)
- FAL Flux Schnell/Dev, Replicate (image generation)
h. **Asset Storage**
- Cloudflare R2 for images, audio, and final videos

##### Relationships & Data Flow
1. Client → FastAPI → Auth endpoint → JWT
2. Client (with token) → Story endpoint → StoryGenerator → OpenAI → returns story text → persisted in DB
3. Client → Image endpoint → ImageGenerator → FAL/Replicate → stores images in R2 → records in DB
4. Client → Video endpoint → VideoTaskProcessor → enqueues background job
5. Background job sequence:
- fetch story & images from DB/R2
- AudioGenerator (TTS) → audio file in R2
- VideoGenerator → combine images + audio + subtitles → upload final video to R2
- Update VideoTask status in DB
6. Client polls status endpoint → fetches final video URL

##### Architectural Patterns & Principles
- **Layered Architecture**: separation of API, core config, services, data access
- **Dependency Injection** via FastAPI for config, DB session, security
- **Asynchronous/Background Processing** for heavy tasks
- **External Integration Points** clearly abstracted in service modules
- **Configuration-Driven Behavior** (feature toggles in config.json)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        Client["Client (Web/CLI)"]:::external
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        FastAPI["FastAPI Server"]:::api
        AuthRouter["Auth Router (/v1/auth)"]:::api
        ImageRouter["Image Router (/v1/image)"]:::api
        VideoRouter["Video Router (/v1/video)"]:::api
        Config["Config Service"]:::core
        Logging["Logging Utilities"]:::core
        Security["Auth & JWT (OAuth2)"]:::core
        Config --> FastAPI
        Logging --> FastAPI
        Security --> FastAPI
        FastAPI --> AuthRouter
        FastAPI --> ImageRouter
        FastAPI --> VideoRouter
    end

    %% Business Services
    subgraph "Business Logic Services"
        direction TB
        StorySvc["StoryGenerator Service"]:::service
        ImageAPI["Image API Wrapper"]:::service
        ImageGen["ImageGenerator Service"]:::service
        AudioSvc["AudioGenerator Service"]:::service
        VideoGen["VideoGenerator Service"]:::service
        VideoTaskProc["VideoTaskProcessor"]:::service
        StorageSvc["Storage Service (Cloudflare R2)"]:::service
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres[(PostgreSQL)]:::db
        R2["Cloudflare R2 Bucket"]:::db
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        OpenAI["OpenAI/Azure OpenAI"]:::external
        FAL["FAL Flux"]:::external
        Replicate["Replicate API"]:::external
    end

    %% Connections
    Client -->|Request| FastAPI
    AuthRouter -->|Auth Request| Security
    AuthRouter -->|Issue JWT| Client
    ImageRouter -->|Image Req with Token| ImageAPI
    ImageAPI -->|Generate Image| FAL
    ImageAPI -->|Generate Image| Replicate
    ImageAPI -->|Store Image| StorageSvc
    ImageGen -->|Record Metadata| Postgres
    StorySvc -->|Generate Story| OpenAI
    StorySvc -->|Store Story| Postgres
    VideoRouter -->|Start Video Task| VideoTaskProc
    VideoTaskProc -->|Background Job| StorySvc
    VideoTaskProc -->|Background Job| ImageGen
    VideoTaskProc -->|Background Job| AudioSvc
    VideoTaskProc -->|Background Job| VideoGen
    AudioSvc -->|TTS| StorageSvc
    VideoGen -->|Compile & Upload| StorageSvc
    StorageSvc -->|Persist| R2
    VideoTaskProc -->|Update Status| Postgres
    Client -->|Poll Status| VideoRouter
    VideoRouter -->|Fetch URL| StorageSvc

    %% Click Events
    click FastAPI "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/main.py"
    click AuthRouter "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/api/endpoints/auth.py"
    click ImageRouter "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/api/endpoints/image.py"
    click VideoRouter "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/api/endpoints/video.py"
    click Config "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/core/config.py"
    click Logging "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/core/logging.py"
    click Security "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/core/security.py"
    click Postgres "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/db/session.py"
    click Postgres "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/db/base_class.py"
    click Postgres "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/db/base.py"
    click Postgres "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/db/init_db.py"
    click Postgres "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/scripts/run_init_db.py"
    click StorySvc "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/services/story_generator.py"
    click ImageAPI "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/services/image_api.py"
    click ImageGen "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/services/image_generator.py"
    click AudioSvc "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/services/audio_generator.py"
    click VideoGen "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/services/video_generator.py"
    click VideoTaskProc "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/services/video_task_processor.py"
    click StorageSvc "https://github.com/jacky-xbb/faceless-video-api/blob/main/app/services/storage.py"
    click Client "https://github.com/jacky-xbb/faceless-video-api/blob/main/README.md"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef core fill:#E8F4FF,stroke:#124E8C,color:#124E8C
    classDef service fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00
    classDef db fill:#FFF4E5,stroke:#E07B39,color:#E07B39
    classDef external fill:#E8FFE8,stroke:#2E8B57,color:#2E8B57
```
