# fal-ai-community/video-starter-kit architecture

> Architecture diagram of the GitHub repository fal-ai-community/video-starter-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fal-ai-community/video-starter-kit
- Repository: https://github.com/fal-ai-community/video-starter-kit

## Overview

##### Project type and purpose
- This is a full-stack, serverless web application (“AI Video Starter Kit”) for building AI-powered video experiences.
- It combines a Next.js/Remotion frontend with serverless API routes that orchestrate video processing, AI model calls, file uploads, and sharing.

##### File structure
- Top-level config & scripts: next.config.mjs, postcss.config.mjs, tailwind.config.ts, tsconfig.json, .env.example, Vercel deployment settings.
- Frontend (src/app & src/components): Next.js “app” directory contains pages, layouts, and client components; src/components holds reusable UI and video-specific controls.
- API layer (src/app/api): four serverless endpoints (download, fal, share, uploadthing) implemented as Next.js Route Handlers.
- Data layer (src/data + src/lib):
- IndexedDB wrappers & schema in src/data (db.ts, store.ts, queries.ts, mutations.ts).
- Business logic & external integrations in src/lib (fal.ai calls, ffmpeg processing, share token logic, file-upload client).
- Utilities & hooks: src/hooks for React hooks (use-toast), helper utils in src/lib/utils.ts.

##### Key insights from README
- Video composition runs in browser via Remotion + ffmpeg WASM.
- AI model integration through fal.ai (Minimax, Hunyuan, LTX).
- Storage is browser-native (IndexedDB) and file uploads via UploadThing.
- Deployment target is Vercel (serverless).

a. Client Browser
- React/Next.js UI
- Remotion video renderer & ffmpeg WASM module
- IndexedDB local store
- Components for camera control, media gallery, timeline, export dialog
b. Next.js Serverless Functions
- /api/download: bundles video assets for download
- /api/fal: proxies requests to fal.ai models
- /api/uploadthing: handles file upload workflows
- /api/share: generates shareable URLs & tokens
c. External Services
- fal.ai API (Minimax, Hunyuan, LTX)
- UploadThing file-upload service
- Vercel hosting & build pipeline
d. Persistence
- IndexedDB (client-side)
- No centralized DB; state is ephemeral or encoded in share links

##### Relationships & interactions
- User interacts with UI → triggers IndexedDB reads/writes and Remotion rendering calls
- UI calls Serverless Functions over HTTP (fetch)
- /api/fal → forwards payload to fal.ai → returns AI response
- /api/uploadthing → negotiates file uploads → UploadThing service → returns file URLs
- /api/download → aggregates video+audio assets → streams ZIP back to client
- /api/share → stores metadata in URL/hash → client retrieves shared state on visit

##### Architectural patterns & principles
- Micro-API routes: each endpoint is a single concern, easily testable and deployable
- Component-based UI with Tailwind/Headless-UI primitives
- Client-side processing for video composition (zero-backend for core video pipeline)
- Clear separation of concerns: UI ↔ data layer ↔ external integrations

##### Technologies to annotate
- Next.js 14 (App Router, Route Handlers)
- Remotion + ffmpeg-wasm
- fal.ai SDK
- UploadThing SDK
- IndexedDB via custom adapters (src/data/db.ts)
- TypeScript for end-to-end type safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser Layer
    subgraph "Client Browser" 
        direction TB
        UI["React/Next.js UI"]:::browser
        SharePage["Share Page"]:::browser
        Components["Reusable UI Components"]:::browser
        Camera["Camera Control"]:::browser
        Gallery["Media Gallery"]:::browser
        Timeline["Timeline & Track"]:::browser
        ExportDialog["Export Dialog"]:::browser
        Remotion["Remotion Renderer & ffmpeg WASM"]:::browser
        IndexedDB["IndexedDB Store & Schema"]:::browser
        Queries["DB Queries & Mutations"]:::browser
        Hooks["React Hooks & Utils"]:::browser
    end

    %% Serverless Backend Layer
    subgraph "Serverless Backend" 
        direction TB
        DownloadAPI["/api/download"]:::serverless
        FalAPI["/api/fal"]:::serverless
        UploadAPI["/api/uploadthing"]:::serverless
        UploadCore["Uploadthing Core Logic"]:::serverless
        ShareAPI["/api/share"]:::serverless
        Utils["Share Logic & Helpers"]:::serverless
        UtilsLib["Utility Functions"]:::serverless
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        FalService["fal.ai Models"]:::external
        UploadService["UploadThing Service"]:::external
        Vercel["Vercel Hosting"]:::external
    end

    %% Connections - Client to IndexedDB
    UI -->|"PUT to IndexedDB"| IndexedDB
    UI -->|"READ from IndexedDB"| Queries
    Queries -->|"apply mutations"| IndexedDB
    UI -->|"WASM call"| Remotion

    %% UI interactions
    UI -->|"uses components"| Components
    UI -->|"loads camera control"| Camera
    UI -->|"loads media gallery"| Gallery
    UI -->|"renders timeline"| Timeline
    UI -->|"opens export dialog"| ExportDialog
    UI -->|"invokes toast"| Hooks

    %% Browser to Serverless
    UI -->|"POST /api/download"| DownloadAPI
    UI -->|"POST /api/fal"| FalAPI
    UI -->|"POST /api/uploadthing"| UploadAPI
    UI -->|"POST /api/share"| ShareAPI
    SharePage -->|"GET share state"| ShareAPI

    %% Serverless to services
    FalAPI ---|"proxy to fal.ai"| FalService
    UploadAPI ---|"negotiate upload"| UploadService
    DownloadAPI -->|"bundle assets"| UtilsLib
    ShareAPI -->|"generate token"| Utils
    UploadAPI -->|"core logic"| UploadCore

    %% Deployment
    DownloadAPI --> Vercel
    FalAPI --> Vercel
    UploadAPI --> Vercel
    ShareAPI --> Vercel

    %% Click Events
    click UI "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/layout.tsx"
    click UI "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/page.tsx"
    click SharePage "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/share/[id]/page.tsx"
    click Components "https://github.com/fal-ai-community/video-starter-kit/tree/main/src/components"
    click Camera "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/components/camera-control.tsx"
    click Gallery "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/components/media-gallery.tsx"
    click Timeline "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/components/video/timeline.tsx"
    click Timeline "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/components/video/track.tsx"
    click ExportDialog "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/components/export-dialog.tsx"
    click Remotion "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/lib/ffmpeg.ts"
    click IndexedDB "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/data/db.ts"
    click IndexedDB "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/data/store.ts"
    click IndexedDB "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/data/schema.ts"
    click Queries "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/data/queries.ts"
    click Queries "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/data/mutations.ts"
    click DownloadAPI "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/api/download/route.ts"
    click FalAPI "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/api/fal/route.ts"
    click UtilsLib "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/lib/utils.ts"
    click UploadAPI "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/api/uploadthing/route.ts"
    click UploadCore "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/api/uploadthing/core.ts"
    click ShareAPI "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/app/api/share/route.ts"
    click Utils "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/lib/share.ts"
    click FalService "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/lib/fal.ts"
    click UploadService "https://github.com/fal-ai-community/video-starter-kit/blob/main/src/lib/uploadthing.ts"

    %% Styles
    classDef browser fill:#e0f7fa,stroke:#0277bd,color:#000
    classDef serverless fill:#e8f5e9,stroke:#2e7d32,color:#000
    classDef external fill:#fff3e0,stroke:#ef6c00,color:#000
```
