# hypercluster-tech/manimator architecture

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

- Interactive diagram: https://gitdiagram.com/hypercluster-tech/manimator
- Repository: https://github.com/hypercluster-tech/manimator

## Overview

##### Project Type and Purpose
- This is a full-stack styled, AI-driven visualization service that exposes both a REST API (FastAPI) and a web UI (Gradio).
- Purpose: Take research papers (ArXiv PDFs) or free-form prompts, generate scene descriptions via LLMs, render animations with Manim, and return MP4 videos.

##### High-Level Components
a. Presentation Layer
- Gradio Web UI (`manimator/gradio_app.py`) running on port 7860
- SwaggerUI on FastAPI docs (`localhost:8000/docs`)
b. API Layer (FastAPI)
- Entrypoint: `manimator/main.py`
- Endpoints organized under `manimator/api/`:
- `scene_description.py` (PDF and prompt→scene description)
- `animation_generation.py` (scene description→animation)
c. Application/Domain Layer
- SceneDescriptionService (uses `utils/system_prompts.py`, `few_shot/few_shot_prompts.py`)
- AnimationService (invokes Manim CLI/programmatic API with quality flags)
d. Infrastructure Layer
- LLM Providers (DeepSeek-V3, Llama 3.3 70B, Gemini via LiteLLM)
- PDF fetcher (ArXiv downloader / multipart upload)
- Manim engine (renders `.py` scenes → `.mp4`)
- Local file system for temp storage (`.gradio/cached_examples`, `/tmp` directories)
- Configuration via `.env` (model endpoints, API keys)
e. Deployment
- Docker container (Dockerfile)
- Poetry or pip for Python dependencies (`pyproject.toml`, `requirements.txt`)

##### Component Interactions and Data Flow
1. User submits a request via:
- Gradio UI → HTTP POST to Gradio server
- Or cURL / client → FastAPI endpoint
2. FastAPI routes request to the appropriate handler in `manimator/api/`.
3. **Scene Description Phase**
- For PDF: download ArXiv PDF → compress → parse → call LLM provider(s) with system prompts & few-shot examples.
- For text prompt: directly call LLM.
- Output: JSON `{ scene_description: "…" }` (Pydantic schema in `utils/schema.py`).
4. **Animation Generation Phase**
- Handler receives scene description → writes a Manim scene file → invokes Manim CLI or Python API with quality flags → generates MP4.
- Cleans up temp files.
5. Response: returns video file (video/mp4) to client.

##### Architectural Patterns & Design Principles
- Layered Architecture: clear separation between Presentation (UI), API, Domain logic, and Infrastructure.
- Modularization:
- `api` package encapsulates HTTP logic.
- `utils` holds shared helper functions, schemas, system prompts.
- `few_shot` and `examples` for sample prompts & demo videos.
- Dependency Injection: environment variables control LLM provider endpoints; easy to swap providers.
- Single Responsibility: each module handles one concern (PDF processing, scene generation, animation rendering).

##### Essential Elements to Capture
- Entrypoints (Gradio & FastAPI)
- Core services (scene generation vs. animation generation)
- External dependencies (LLMs, ArXiv PDF)
- Data schemas (Pydantic) and temp storage
- Deployment boundary (Docker)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Boundary
    subgraph "Docker Container"
        direction TB

        %% Presentation Layer
        subgraph "Presentation Layer"
            direction TB
            Gradio["Gradio Web UI<br/>(Gradio)"]:::presentation
            Swagger["SwaggerUI / cURL"]:::presentation
        end

        %% API Layer
        subgraph "API Layer"
            direction TB
            FastAPI["FastAPI Server<br/>(manimator/main.py)"]:::api
            SceneAPI["Scene Description Endpoint<br/>(FastAPI)"]:::api
            AnimAPI["Animation Generation Endpoint<br/>(FastAPI)"]:::api
        end

        %% Domain Layer
        subgraph "Domain Layer"
            direction TB
            SceneService["SceneDescriptionService"]:::domain
            AnimationService["AnimationService"]:::domain
            Prompts["System Prompts"]:::domain
            FewShot["Few-Shot Prompts"]:::domain
            Schema["Pydantic Schemas"]:::domain
        end

        %% Infrastructure Layer
        subgraph "Infrastructure Layer"
            direction TB
            LLM["LLM Providers"]:::external
            ArXiv["ArXiv PDF Server"]:::external
            Manim["Manim Engine"]:::infra
            FileSys["Temp File System"]:::infra
            Helpers["Helper Utilities"]:::infra
            Cache["Cached Examples"]:::infra
            Examples["Example Videos"]:::infra
        end

        %% Configuration & Dependencies
        subgraph "Configuration & Dependencies"
            direction TB
            DockerfileNode["Dockerfile"]:::deployment
            PyProj["pyproject.toml"]:::deployment
            Req["requirements.txt"]:::deployment
            Env[".env.example"]:::deployment
        end

    end

    %% Connections
    Gradio -->|"POST /generate"| FastAPI
    Swagger -->|"HTTP Request"| FastAPI

    FastAPI -->|"scene request"| SceneAPI
    FastAPI -->|"animation request"| AnimAPI

    SceneAPI -->|"invoke"| SceneService
    SceneService -->|"download PDF"| ArXiv
    SceneService -->|"use prompts"| Prompts
    SceneService -->|"use prompts"| FewShot
    SceneService -->|"validate data"| Schema
    SceneService -->|"temp storage"| FileSys
    SceneService -->|"call LLM"| LLM
    SceneService -->|"return description"| FastAPI

    AnimAPI -->|"invoke"| AnimationService
    AnimationService -->|"generate scene file"| FileSys
    AnimationService -->|"render video"| Manim
    AnimationService -->|"cleanup"| FileSys
    AnimationService -->|"use utils"| Helpers
    AnimationService -->|"return video"| FastAPI

    FastAPI -->|"response MP4"| Gradio
    FastAPI -->|"response MP4"| Swagger

    %% Infra Assets
    Cache -.-> Gradio
    Examples -.-> Gradio

    %% Click Events
    click Gradio "https://github.com/hypercluster-tech/manimator/blob/main/manimator/gradio_app.py"
    click FastAPI "https://github.com/hypercluster-tech/manimator/blob/main/manimator/main.py"
    click SceneAPI "https://github.com/hypercluster-tech/manimator/blob/main/manimator/api/scene_description.py"
    click AnimAPI "https://github.com/hypercluster-tech/manimator/blob/main/manimator/api/animation_generation.py"
    click Prompts "https://github.com/hypercluster-tech/manimator/blob/main/manimator/utils/system_prompts.py"
    click FewShot "https://github.com/hypercluster-tech/manimator/blob/main/manimator/few_shot/few_shot_prompts.py"
    click Schema "https://github.com/hypercluster-tech/manimator/blob/main/manimator/utils/schema.py"
    click Helpers "https://github.com/hypercluster-tech/manimator/blob/main/manimator/utils/helpers.py"
    click Cache "https://github.com/hypercluster-tech/manimator/tree/main/manimator/.gradio/cached_examples"
    click Examples "https://github.com/hypercluster-tech/manimator/tree/main/manimator/examples"
    click DockerfileNode "https://github.com/hypercluster-tech/manimator/tree/main/Dockerfile"
    click PyProj "https://github.com/hypercluster-tech/manimator/blob/main/pyproject.toml"
    click Req "https://github.com/hypercluster-tech/manimator/blob/main/requirements.txt"
    click Env "https://github.com/hypercluster-tech/manimator/blob/main/.env.example"

    %% Styles
    classDef presentation fill:#CFE2F3,stroke:#3182CE,color:#0B3D91;
    classDef api fill:#D5E8D4,stroke:#379237,color:#225522;
    classDef domain fill:#FFE599,stroke:#E69138,color:#974F0C;
    classDef external fill:#E1D5E7,stroke:#9673A6,color:#4A235A;
    classDef infra fill:#D9D9D9,stroke:#7F7F7F,color:#404040;
    classDef deployment fill:#F4CCCC,stroke:#CC0000,color:#912D3E;
```
