# akramj13/ai-video architecture

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

- Interactive diagram: https://gitdiagram.com/akramj13/ai-video
- Repository: https://github.com/akramj13/ai-video

## Overview

##### Project Type & Purpose
- This is a full-stack web application that generates voice-overs for short-form videos. It provides user authentication, content generation, captioning, and styling options integrated with multiple third-party AI services.
- The README highlights key features like topic customization, multiple generated styles, and high-quality voice synthesis using external providers. The frontend uses Next.js (App Router), React, Tailwind CSS, and shadcn/ui, while the backend leverages APIs to interface with services like ElevenLabs, AssemblyAI, Google Gemini, and more.

##### File Structure
- The top-level directories include “app” (which holds the Next.js pages and routes), “configs” (database, model, and schema configurations), “lib” (utility functions), and other configuration files (next.config.mjs, drizzle.config.js, etc.).
- Under the “app” directory you have clearly defined subdirectories:
- (auth): Contains nested sign-in and sign-up pages for user authentication.
- api: Includes API routes for generating audio, generating captions, and video script generation.
- dashboard and its subdirectories: Indicate the user dashboard for creating and managing projects, with dedicated components like Header, SideNav, and project creation UI components (SelectDuration, SelectStyle, SelectTopic).
- The existence of middleware, a provider, theme toggle, and client-side UI components further implies a clear separation of concerns consistent with modern web app architecture.

##### Key Components
a. Frontend Layer:
- Auth Module: Clearly illustrate the sign-in and sign-up flows, which integrate with Clerk for secure authentication.
- Dashboard & Project Creation Pages: These components form the user interaction layer that lets users select topics and styles for voice synthesis.
- UI Components: Represent custom shadcn/ui-based elements (alerts, buttons, dropdown menus, etc.) used across the application.

b. Backend & API Layer:
- API Endpoints: Show individual API routes (e.g., /api/generate-audio, /api/generate-caption, /api/get-video-script) and note how these routes trigger specific AI or processing operations.
- Business Logic: Highlight the integration of Google Gemini AI for content generation, ElevenLabs for voice synthesis, AssemblyAI for automatic captioning, and how these endpoints interact with the backend.

c. External Services and Integrations:
- Cloud Services & Storage: Include AWS S3 for file storage.
- Database Layer: Represent the Neon Database (PostgreSQL) accessed via Drizzle ORM, with configuration files (e.g., configs/db.js, drizzle.config.js).
- Authentication Provider: Include Clerk as the external service handling authentication and user management.
- Third-Party APIs: Clearly denote the integration points with ElevenLabs, AssemblyAI, Google Gemini, etc.

d. Deployment & Infrastructure:
- Hosting: Note that the application is deployed on Vercel.
- Development & Build Environment: Mention build/configuration aspects such as Next.js configuration (next.config.mjs), PostCSS, Tailwind, ESLint, etc.

##### Relationships and Interactions
- How the API endpoints interact with external AI services and then return their responses to the frontend.
- Role of authentication: user sessions managed via Clerk are processed before granting access to the dashboard and API endpoints.
- Data flow from the API endpoints to the Neon Database (with Drizzle ORM handling persistence) for logging and retrieval of generated content.

##### Architectural Patterns & Design Principles
- Separation between presentation (React/Next.js components) and business logic/API routes.
- Use modern single-page application principles with server-driven UI (Next.js App Router) and microservices-like API endpoints.
- Responsiveness and reactive nature of the UI coupled with the backend’s reliance on asynchronous processing for AI interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Entity
    User("User"):::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE_Shell("Next.js App Shell"):::frontend
        Auth("Authentication (Clerk)"):::frontend
        Dashboard("Dashboard & Project Creation"):::frontend
        UI("UI Components (shadcn/ui)"):::frontend
    end

    %% External Authentication Service
    ClerkExt("Authentication Provider (Clerk)"):::external

    %% Backend & API Layer
    subgraph "Backend & API Layer"
        API("API Endpoints"):::backend
        Middleware("Middleware"):::middleware
        Business("Business Logic & AI Integrations"):::backend
        DB("Neon Database (PostgreSQL)"):::database
        Utils("Utility Functions"):::utility
    end

    %% External Services and Integrations
    subgraph "External Services"
        S3("AWS S3 (Storage)"):::external
        ElevenLabs("ElevenLabs API"):::external
        AssemblyAI("AssemblyAI API"):::external
        GoogleGemini("Google Gemini AI"):::external
    end

    %% Deployment Environment
    Vercel("Deployment (Vercel)"):::deployment

    %% Relationships and Data Flow
    User -->|"RequestPage"| FE_Shell
    FE_Shell -->|"initAuth"| Auth
    FE_Shell -->|"renderDashboard"| Dashboard
    FE_Shell -->|"includeUI"| UI
    Auth -->|"validateUser"| ClerkExt

    Dashboard -->|"submitData"| API
    FE_Shell ---|"utilizes"| Utils
    API ---|"utilizes"| Utils
    API -->|"preProcess"| Middleware
    API -->|"processRequest"| Business
    API -->|"persistData"| DB
    Business -->|"storeOutput"| S3
    Business -->|"voiceSynthesis"| ElevenLabs
    Business -->|"captionGeneration"| AssemblyAI
    Business -->|"contentGen"| GoogleGemini

    FE_Shell -->|"deployedOn"| Vercel
    API -->|"deployedOn"| Vercel

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef middleware fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef utility fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef deployment fill:#BB8FCE,stroke:#8E44AD,stroke-width:2px;

    %% Click Events for Component Mappings
    click FE_Shell "https://github.com/akramj13/ai-video/blob/main/app/layout.js"
    click FE_Shell "https://github.com/akramj13/ai-video/blob/main/app/page.js"
    click FE_Shell "https://github.com/akramj13/ai-video/blob/main/app/provider.js"

    click Auth "https://github.com/akramj13/ai-video/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.jsx"
    click Auth "https://github.com/akramj13/ai-video/blob/main/app/(auth)/sign-up/[[...sign-up]]/page.jsx"

    click Dashboard "https://github.com/akramj13/ai-video/blob/main/app/dashboard/page.jsx"
    click Dashboard "https://github.com/akramj13/ai-video/blob/main/app/dashboard/layout.jsx"
    click Dashboard "https://github.com/akramj13/ai-video/tree/main/app/dashboard/create-new/"

    click UI "https://github.com/akramj13/ai-video/tree/main/components/ui/"
    click UI "https://github.com/akramj13/ai-video/blob/main/components/theme-provider.jsx"
    click UI "https://github.com/akramj13/ai-video/blob/main/components/theme-toggle.jsx"

    click API "https://github.com/akramj13/ai-video/blob/main/app/api/generate-audio/route.js"
    click API "https://github.com/akramj13/ai-video/blob/main/app/api/generate-caption/route.js"
    click API "https://github.com/akramj13/ai-video/blob/main/app/api/get-video-script/route.js"

    click DB "https://github.com/akramj13/ai-video/blob/main/configs/db.js"
    click DB "https://github.com/akramj13/ai-video/blob/main/configs/model.js"
    click DB "https://github.com/akramj13/ai-video/blob/main/configs/schema.js"
    click DB "https://github.com/akramj13/ai-video/blob/main/drizzle.config.js"

    click Utils "https://github.com/akramj13/ai-video/blob/main/lib/utils.js"

    click Middleware "https://github.com/akramj13/ai-video/blob/main/middleware.js"
```
