MLanim is a full-stack web application that generates beautiful mathematical animations from natural language descriptions using Google Gemini AI and the Manim animation library.
- AI-Powered Generation: Uses Google Gemini to understand natural language prompts and generate valid Manim code
- Safe Execution: All code runs in isolated Docker containers to prevent arbitrary code execution
- Asynchronous Processing: Job queue system for handling multiple animation requests
- Real-time Updates: Live status updates and progress tracking
- High-Quality Output: Professional-grade animations rendered with Manim
- Modern UI: Beautiful React frontend with Tailwind CSS styling
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ React Frontend│ │ Node.js Backend│ │ Redis Queue │
│ (Port 3000) │◄──►│ (Port 3001) │◄──►│ (Port 6379) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Docker + Manim │
│ (Rendering) │
└─────────────────┘
- React 18 with TypeScript
- Tailwind CSS for styling
- Vite for build tooling
- Axios for API communication
- Node.js with TypeScript
- Express.js web framework
- BullMQ for job queue management
- Redis for queue persistence
- Winston for logging
- Helmet for security
- Manim (Python) for mathematical animations
- Docker for safe code execution
- Google Gemini API for AI code generation
Before running MLanim, ensure you have the following installed:
- Node.js (v18 or higher)
- Docker and Docker Compose
- Redis (or use the Docker container)
- Google Gemini API Key
git clone https://github.com/yourusername/mlanim.git
cd mlanim# Install root dependencies
npm install
# Install backend dependencies
cd backend && npm install && cd ..
# Install frontend dependencies
cd frontend && npm install && cd ..Create a .env file in the backend directory:
cd backend
cp env.example .envEdit .env with your configuration:
# Server Configuration
PORT=3001
NODE_ENV=development
# Google Gemini API (Required)
GEMINI_API_KEY=your_actual_gemini_api_key_here
# Redis Configuration
REDIS_URL=redis://localhost:6379
# File Storage
OUTPUT_DIR=./outputs
MAX_FILE_SIZE=100mb
# Security
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
# Logging
LOG_LEVEL=info# Start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down# Using Docker
docker run -d --name redis -p 6379:6379 redis:7-alpine
# Or install locally
# macOS: brew install redis
# Ubuntu: sudo apt-get install redis-servercd backend
npm run devcd frontend
npm run dev- Frontend: http://localhost:3000
- Backend API: http://localhost:3001
- Health Check: http://localhost:3001/health
npm run dev # Start both frontend and backend
npm run build # Build both applications
npm run lint # Lint all code
npm run format # Format all code
npm run install:all # Install all dependenciescd backend
npm run dev # Start development server
npm run build # Build for production
npm run start # Start production server
npm run lint # Lint TypeScript code
npm run format # Format code with Prettiercd frontend
npm run dev # Start development server
npm run build # Build for production
npm run preview # Preview production build
npm run lint # Lint TypeScript code
npm run format # Format code with Prettiermlanim/
├── backend/ # Node.js backend
│ ├── src/
│ │ ├── config/ # Configuration management
│ │ ├── controllers/ # Express route controllers
│ │ ├── middleware/ # Express middleware
│ │ ├── routes/ # API route definitions
│ │ ├── services/ # Business logic services
│ │ ├── types/ # TypeScript type definitions
│ │ ├── utils/ # Utility functions
│ │ ├── app.ts # Express app setup
│ │ └── index.ts # Server entry point
│ ├── Dockerfile # Backend container
│ └── package.json
├── frontend/ # React frontend
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── services/ # API service layer
│ │ ├── types/ # TypeScript types
│ │ ├── App.tsx # Main app component
│ │ └── main.tsx # App entry point
│ ├── Dockerfile # Frontend container
│ └── package.json
├── docker-compose.yml # Service orchestration
└── README.md
- Code Sandboxing: All Manim code runs in isolated Docker containers
- Input Validation: Comprehensive validation of user inputs and generated code
- Rate Limiting: API rate limiting to prevent abuse
- Security Headers: Helmet.js for security headers
- CORS Protection: Configured CORS policies
- Code Analysis: Pattern-based detection of potentially dangerous code
POST /api/animations/generate- Generate animation from promptGET /api/animations/status/:id- Get job statusGET /api/animations/jobs- Get all jobs (monitoring)
GET /health- Health checkGET /- API information
- redis: Redis database for job queue
- backend: Node.js API server
- frontend: React application with Nginx
outputs/: Generated animation filestemp/: Temporary files during renderinglogs/: Application logs
mlanim-network: Isolated network for services
- Backend logs:
backend/logs/ - Frontend logs: Docker container logs
- Redis logs: Docker container logs
- Backend:
http://localhost:3001/health - Frontend:
http://localhost:3000/health - Redis: Docker health check
# Check if Docker is running
docker --version
docker-compose --version
# Restart Docker services
docker-compose restart
# View service logs
docker-compose logs [service-name]# Test Redis connection
redis-cli ping
# Check Redis container
docker ps | grep redis# Check Docker container logs
docker-compose logs backend
# Verify Manim image
docker pull manimcommunity/manim:latest# Verify environment variable
echo $GEMINI_API_KEY
# Check backend logs for API errors
docker-compose logs backend | grep "gemini"- Adjust
RATE_LIMIT_MAX_REQUESTSin.env - Modify
MAX_FILE_SIZEfor larger animations - Tune Redis connection pool
- Adjust polling interval in
App.tsx - Optimize bundle size with Vite
- Enable production optimizations
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Commit changes:
git commit -am 'Add feature' - Push to branch:
git push origin feature-name - Submit a pull request
- Follow TypeScript best practices
- Use ESLint and Prettier for code formatting
- Write meaningful commit messages
- Add tests for new features
- Update documentation as needed