# zkamdar1/nebula architecture

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

- Interactive diagram: https://gitdiagram.com/zkamdar1/nebula
- Repository: https://github.com/zkamdar1/nebula

## Overview

##### Main Components
- Backend API Server: Built on FastAPI. Its primary responsibilities include handling API endpoints (authentication, project management, generation requests) and orchestrating the video creation process.
- Video Generation Module: A distinct set of submodules within the backend (script generation, audio generation, video editing, subtitle processing, music integration). Each of these submodules (found inside backend/video_generator) should be highlighted.
- Database & Infrastructure: Implementation using SQLAlchemy as ORM, PostgreSQL (which may be hosted on AWS RDS), and integration with external storage (AWS S3) for video and asset management.
- Utility / Service Modules: Modules under backend/utils (for authentication utilities, database connection, Firebase helpers, S3 operations) which support the core functionalities.
- Frontend Application: A React-based UI that communicates with the backend via RESTful endpoints. It utilizes components, pages, and services (like API calls and Firebase for authentication).
- External Services: Tools like OpenAI for script generation, Google TTS, and Google Speech-to-Text APIs for audio narration and subtitle generation.

##### Architectural Patterns and Design Principles
- Modularity: The clear separation of concerns between the different parts of the video generation process.
- Separation of Frontend and Backend: Show distinct layers with well-defined communication (HTTP/REST API calls).
- Incorporate error handling and health checks through the API endpoints.

- Backend Container:
- API Endpoints block: auth.py, projects.py, generate.py, health.py.
- Business Logic block: Video Generator modules (script, audio, video, subtitle, music) along with asset management.
- Database block: Models and schemas interfacing via SQLAlchemy with PostgreSQL (plus AWS RDS).
- Utility block: Utilities for auth, database management, S3 operations, and Firebase.
- Frontend Container:
- React Components and Pages: Highlight components from frontend/src/components and pages from frontend/src/pages.
- Services: Represent the API service integration (communicating with the backend) and Firebase services for authentication.
- External and Cloud Services:
- AWS S3 and AWS RDS resources.
- Third-party APIs: OpenAI, Google TTS/ Speech-to-Text.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Container
    subgraph "Backend"
        API_Endpoints["FastAPI API Endpoints"]:::api
        subgraph "Video Generation Pipeline"
            ScriptGen["Script Generation"]:::video
            AudioGen["Audio Generation"]:::video
            VideoEdit["Video Editing"]:::video
            SubtitleProc["Subtitle Processing"]:::video
            MusicInt["Music Integration"]:::video
        end
        Util["Utility Services (Auth, DB, S3, Firebase)"]:::util
        Database["Database (SQLAlchemy Models & Schemas)"]:::db

        API_Endpoints -->|"calls"| ScriptGen
        ScriptGen -->|"calls"| AudioGen
        AudioGen -->|"calls"| VideoEdit
        VideoEdit -->|"calls"| SubtitleProc
        SubtitleProc -->|"calls"| MusicInt
        
        API_Endpoints -->|"uses"| Util
        API_Endpoints -->|"reads/writes"| Database
    end

    %% Frontend Container
    subgraph "Frontend"
        FrontendUI["React Components & Pages"]:::frontend
        FrontendService["API & Firebase Services"]:::frontend
        FrontendUI -->|"calls"| FrontendService
        FrontendService -->|"communicates"| API_Endpoints
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI GPT"]:::external
        GoogleTTS["Google TTS"]:::external
        GoogleSpeech["Google Speech-to-Text"]:::external
        AWSS3["AWS S3"]:::external
        AWSRDS["AWS RDS"]:::external
    end

    %% External Integrations
    ScriptGen -->|"uses"| OpenAI
    AudioGen -->|"uses"| GoogleTTS
    SubtitleProc -->|"uses"| GoogleSpeech
    MusicInt -->|"uploads"| AWSS3
    Database -->|"hosted_on"| AWSRDS

    %% Click Events for Backend Components
    click API_Endpoints "https://github.com/zkamdar1/nebula/tree/main/backend/api"
    click ScriptGen "https://github.com/zkamdar1/nebula/blob/main/backend/video_generator/script_generation/script.py"
    click AudioGen "https://github.com/zkamdar1/nebula/blob/main/backend/video_generator/audio_generation/audio.py"
    click VideoEdit "https://github.com/zkamdar1/nebula/blob/main/backend/video_generator/video_editing/video.py"
    click SubtitleProc "https://github.com/zkamdar1/nebula/blob/main/backend/video_generator/sub_generation/sub.py"
    click MusicInt "https://github.com/zkamdar1/nebula/blob/main/backend/video_generator/music_generation/music.py"
    click Database "https://github.com/zkamdar1/nebula/tree/main/backend/models"
    click Util "https://github.com/zkamdar1/nebula/tree/main/backend/utils"

    %% Click Events for Frontend Components
    click FrontendUI "https://github.com/zkamdar1/nebula/tree/main/frontend/src/components"
    click FrontendService "https://github.com/zkamdar1/nebula/tree/main/frontend/src/services"

    %% Style Classes
    classDef api fill:#ffcccb,stroke:#b30000,stroke-width:2px;
    classDef video fill:#ccffcc,stroke:#228B22,stroke-width:2px;
    classDef db fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef util fill:#ffffcc,stroke:#b3b300,stroke-width:2px;
    classDef frontend fill:#ffebcc,stroke:#ff8c00,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#808080,stroke-width:2px;
```
