AnimaStudio

A full-stack graph visualization service that renders beautiful animations using Manim.

Stack

Frontend

• Next.js 14 (App Router)
• TypeScript
• Tailwind CSS
• shadcn/ui components

Backend

• FastAPI + Uvicorn
• Python 3.11
• PostgreSQL database
• SQLAlchemy 2.0 (async) + asyncpg
• Alembic migrations
• Celery + Redis for task queue
• Manim for rendering (in Docker container)

DevOps

• Docker Compose orchestration
• Local file storage with shared volumes
• Pydantic v2 for settings
• ruff + black + pytest for code quality

Features

• ✅ AI-powered animation planning with Gemini
• ✅ Natural language prompts for graph creation
• ✅ Asynchronous rendering with Celery workers
• ✅ Real-time job status polling
• ✅ Clean animations with rounded rectangles and smooth transitions
• ✅ Video playback in browser
• ✅ View LLM-generated animation plan, code, and logs
• ✅ Validate and sanitize user inputs
• ✅ PostgreSQL persistence with migrations

Architecture

┌─────────────┐
│   Next.js   │  (port 3000)
│   Frontend  │
└──────┬──────┘
       │ HTTP
       ▼
┌─────────────┐
│   FastAPI   │  (port 8000)
│     API     │
└──────┬──────┘
       │
       ├─────► PostgreSQL (port 5432)
       │
       └─────► Redis (port 6379)
              │
              ▼
       ┌─────────────┐
       │   Celery    │
       │   Worker    │
       └──────┬──────┘
              │
              ▼
       ┌─────────────┐
       │   Manim     │
       │  Renderer   │
       └─────────────┘

Setup Instructions

Prerequisites

• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• Docker Compose v2.0+
• Git

1. Clone Repository

git clone <your-repo-url>
cd AnimaStudio

2. Environment Configuration

Windows PowerShell:

Copy-Item .env.example .env

macOS/Linux:

cp .env.example .env

Edit .env and add your Gemini API key:

GEMINI_API_KEY=your-actual-api-key-here

Get your free API key at: https://aistudio.google.com/app/apikey

3. Start All Services

Windows PowerShell:

docker-compose up --build

macOS/Linux:

docker-compose up --build

This command will:

• Build all Docker images
• Start PostgreSQL, Redis, API, Worker, Manim, and Frontend
• Create necessary volumes and networks

4. Run Database Migrations

Open a new terminal and run:

Windows PowerShell:

docker exec -it anima_api alembic upgrade head

macOS/Linux:

docker exec -it anima_api alembic upgrade head

5. Access the Application

Open your browser and navigate to:

http://localhost:3000

The API documentation is available at:

http://localhost:8000/docs

Usage

Creating a Graph Animation

1. Enter a natural language prompt describing your desired graph, e.g.:

   Explain cache miss with client server cache db
   

   or

   Show login flow: user -> frontend -> api -> database
   

2. Click "Generate Graph Animation"

3. The AI (Gemini) will create a structured animation plan with nodes, edges, and animation steps

4. Wait for rendering to complete (status updates automatically)

5. Watch the rendered video with smooth animations

6. Expand sections to view:

   • LLM Animation Plan - Structured plan generated by AI
   • Generated Code - Safe Manim code produced from the plan
   • Logs - Execution details

Example Prompts

System Architecture:

Microservices: API Gateway connects to Auth Service and User Service, both connect to Database

Data Flow:

Explain cache miss with client server cache db

Process Flow:

Show login flow: user -> frontend -> api -> database

Network Topology:

Create a star network with central router and 4 clients

Algorithm:

Binary search tree: insert 5, then 3, then 7, highlight the path

How It Works

1. AI Planning: Gemini analyzes your prompt and generates a structured AnimationPlan (JSON)
2. Safe Codegen: Our controlled code generator creates Manim Python code from the plan
3. Rendering: Manim renders the animation in an isolated Docker container
4. Delivery: Video is stored and served for playback

Important: The AI only creates the animation plan (nodes, edges, steps). The actual Python code is generated by our safe, deterministic code generator - never by the LLM.

API Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
POST	/api/jobs	Create rendering job
GET	/api/jobs/{id}	Get job status and details
GET	/api/videos/{file}	Serve rendered video file

Project Structure

AnimaStudio/
├── backend/
│   ├── alembic/
│   │   ├── versions/
│   │   │   └── 001_initial_migration.py
│   │   ├── env.py
│   │   └── script.py.mako
│   ├── app/
│   │   ├── api/
│   │   │   └── routes.py
│   │   ├── core/
│   │   │   └── config.py
│   │   ├── db/
│   │   │   ├── base.py
│   │   │   └── session.py
│   │   ├── models/
│   │   │   └── job.py
│   │   ├── schemas/
│   │   │   └── job.py
│   │   ├── worker/
│   │   │   ├── celery_app.py
│   │   │   └── tasks.py
│   │   └── main.py
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── pyproject.toml
│   └── alembic.ini
├── frontend/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   └── ui/
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       ├── textarea.tsx
│   │       ├── alert.tsx
│   │       └── collapsible.tsx
│   ├── lib/
│   │   └── utils.ts
│   ├── Dockerfile
│   ├── package.json
│   ├── tsconfig.json
│   ├── next.config.js
│   ├── tailwind.config.ts
│   └── postcss.config.js
├── docker/
│   └── manim/
│       └── Dockerfile
├── outputs/
│   └── .gitkeep
├── docker-compose.yml
├── .env.example
├── .gitignore
└── README.md

Development

Backend

Run tests:

docker exec -it anima_api pytest

Format code:

docker exec -it anima_api black app/
docker exec -it anima_api ruff check app/

Create new migration:

docker exec -it anima_api alembic revision --autogenerate -m "description"

Frontend

Install dependencies locally (optional for IDE support):

cd frontend
npm install

Logs

View API logs:

docker logs -f anima_api

View worker logs:

docker logs -f anima_worker

View all services:

docker-compose logs -f

Troubleshooting

Issue: Services won't start

Solution:

• Ensure Docker Desktop is running
• Check ports 3000, 8000, 5432, 6379 are not in use
• Run: docker-compose down -v then docker-compose up --build

Issue: Database connection errors

Solution:

# Wait for PostgreSQL to be ready
docker-compose down
docker-compose up -d postgres
# Wait 10 seconds
docker-compose up -d api worker

Issue: Migrations fail

Solution:

# Reset database
docker-compose down -v
docker-compose up -d postgres
# Wait 10 seconds
docker exec -it anima_api alembic upgrade head
docker-compose up -d

Issue: Worker can't find Manim container

Solution:

# Ensure manim-renderer is built
docker-compose build manim-renderer
docker-compose up -d manim-renderer
docker-compose restart worker

Issue: Videos not playing

Solution:

• Check browser console for errors
• Verify file exists: ls outputs/
• Check API logs: docker logs anima_api
• Ensure video file permissions: docker exec -it anima_api ls -la /app/outputs

Issue: Frontend can't reach API

Solution:

• Check .env has NEXT_PUBLIC_API_URL=http://localhost:8000
• Verify API is running: curl http://localhost:8000/api/health
• Rebuild frontend: docker-compose up --build web

Issue: Celery tasks not executing

Solution:

# Check Redis connection
docker exec -it anima_redis redis-cli ping
# Should return "PONG"

# Restart worker
docker-compose restart worker

# Check worker logs
docker logs -f anima_worker

Stopping Services

Windows PowerShell / macOS / Linux:

docker-compose down

Remove volumes (⚠️ deletes database data):

docker-compose down -v

Production Considerations

This is a local development setup. For production:

1. Use managed PostgreSQL (e.g., AWS RDS, Azure Database)
2. Use managed Redis (e.g., AWS ElastiCache, Azure Cache)
3. Configure proper CORS origins
4. Add authentication/authorization
5. Use production-grade reverse proxy (nginx)
6. Implement rate limiting
7. Add monitoring and logging (e.g., Sentry, DataDog)
8. Use environment-specific .env files
9. Enable HTTPS/TLS
10. Scale workers horizontally based on load

License

MIT

Contributing

Pull requests welcome! Please ensure:

• Code passes ruff and black checks
• Tests are included for new features
• Documentation is updated

---

Built with ❤️ using FastAPI, Next.js, and Manim