CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MiniMax Tools is a FastAPI-based web application providing four AI-powered tools that integrate with the MiniMax API:

• Music generation (text-to-music with lyrics)
• Image generation (text-to-image)
• Vision Language Model (VLM) for image analysis
• Voice design (text-to-speech with custom voice characteristics)

The application is deployed via Docker with monitoring, rate limiting, and automatic data cleanup.

Development Commands

Starting the Application

# Quick start (recommended)
./start.sh

# Manual start
sudo docker compose up -d --build

# View logs
sudo docker compose logs -f

# Stop service
sudo docker compose down

# Clean all data (including volumes)
sudo docker compose down -v

Local Development

# Install dependencies
pip install -r requirements.txt

# Run locally (from app/ directory)
cd app
uvicorn main:app --host 0.0.0.0 --port 5213 --reload

# Or using Python directly
python main.py

Testing Endpoints

The application runs on http://localhost:5213 with these key endpoints:

• / - Main homepage
• /music - Music generation interface
• /image-generation - Image generation interface
• /vlm - Vision Language Model interface
• /voice-design - Voice design interface
• /admin - Monitoring dashboard (stats and metrics)

Architecture

Application Structure

app/
 main.py              # FastAPI app initialization, middleware setup, route registration
 routes/              # Route handlers for each feature
    music.py         # Music generation (POST /music/generate, file download/streaming)
    image_generation.py
    vlm.py
    voice_design.py
 utils/               # Core utility modules
    monitor.py       # SQLite-based API call monitoring and statistics
    rate_limiter.py  # In-memory rate limiting (per-IP tracking)
    cleanup.py       # Background thread for temp file and rate limit cleanup
 templates/           # Jinja2 HTML templates

Key Architectural Patterns

1. Monitoring System (utils/monitor.py)

• Uses SQLite database (monitor.db) to track all API calls
• Middleware captures: endpoint, IP, user agent, status code, response time
• Statistics aggregated over 24-hour windows
• Accessed via /admin endpoint

2. Rate Limiting (utils/rate_limiter.py)

• In-memory implementation using defaultdict and threading locks
• Per-IP tracking with sliding time windows
• Different limits per feature:
  • Music: 5 requests / 5 minutes
  • Image generation: 5 requests / 5 minutes
  • VLM analysis: 10 requests / 5 minutes
  • Voice design: 5 requests / 5 minutes
• Called via check_rate_limit(request, max_requests, window_seconds)

3. Data Cleanup (utils/cleanup.py)

• Background daemon thread started on app initialization
• Runs every 15 minutes (900 seconds)
• Deletes files in tmp/ older than 1 hour
• Also cleans expired rate limit records
• Session-based temp directories: tmp/{session_id}/

4. Session Management

• Each user request creates a unique session directory via create_user_session_dir()
• Returns session UUID for file isolation
• Files served via /download/{session_id}/{filename} and /stream/{session_id}/{filename}

5. MiniMax API Integration Pattern All route modules follow similar patterns:

# 1. Rate limit check
check_rate_limit(request, max_requests=5, window_seconds=300)

# 2. Create session directory
session_dir, session_id = create_user_session_dir()

# 3. Call MiniMax API with user's API key (passed via form)
headers = {'Authorization': 'Bearer ' + api_key}
response = requests.post(minimax_url, headers=headers, data=payload)

# 4. Process and save result to session directory
# 5. Return download/stream URLs with session_id

Important Implementation Details

API Key Handling

• API keys are NOT stored; passed via form data on each request
• Each user provides their own MiniMax API key
• Keys are only used for that single request

File Storage

• User files stored in tmp/{session_id}/ for isolation
• All files auto-deleted after 1 hour
• Docker volumes: ./tmp:/app/tmp and ./data:/app/data

Static Files

• Note: app/static/ directory is expected but may not exist in initial setup
• Mount point defined in main.py: app.mount("/static", StaticFiles(directory="static"))
• If adding static assets, create app/static/ directory

Database

• Monitoring uses SQLite (monitor.db)
• No user data stored in database
• Only API call metadata and statistics

Adding New Features

To add a new MiniMax API integration:

1. Create new route file in app/routes/new_feature.py
2. Follow the standard pattern:
   • Import check_rate_limit and create_user_session_dir
   • Create router: router = APIRouter()
   • Add GET route for HTML page
   • Add POST route for API call with rate limiting
   • Add download/stream routes if handling files
3. Create HTML template in app/templates/new_feature.html
4. Register router in app/main.py:

   from routes import new_feature
   app.include_router(new_feature.router, prefix="/new-feature", tags=["New Feature"])
   

5. Add link to homepage template (templates/index.html)

Configuration

Environment Variables (Optional)

Rate limiting and cleanup can be configured via environment variables in docker-compose.yml:

environment:
  - DEFAULT_RATE_LIMIT_REQUESTS=10
  - DEFAULT_RATE_LIMIT_WINDOW=60
  - CLEANUP_INTERVAL_MINUTES=15
  - FILE_RETENTION_HOURS=1

Note: Currently these are hardcoded in the application; environment variable support would need to be added.

Docker Build

• Base image: python:3.11-slim
• Uses Chinese mirrors (Tsinghua) for faster builds in China
• System packages: mpv, curl
• Port: 5213
• Working directory: /app

Debugging

Common Issues

Files not found (404 on download)

• Check if cleanup task deleted files (files expire after 1 hour)
• Verify session directory creation in route handlers
• Check Docker volume mounts: ./tmp:/app/tmp

Rate limit errors (429)

• Rate limits are per-IP, check rate_limit_store in memory
• Default: 5 requests per 5 minutes for most features
• Wait for time window to expire or adjust limits in route code

MiniMax API errors

• Verify user's API key is valid
• Check MiniMax API status
• Review error details in response from MiniMax API
• Monitor endpoint: check /admin for error rates

Static files not loading

• Ensure app/static/ directory exists
• Check Docker build copied static files
• Verify mount in main.py:14

Monitoring and Logs

# View all logs
sudo docker compose logs -f

# Check database stats
sqlite3 monitor.db "SELECT * FROM api_calls ORDER BY timestamp DESC LIMIT 10;"

# View monitoring dashboard
# Visit http://localhost:5213/admin

Dependencies

Key Python packages:

• fastapi - Web framework
• uvicorn - ASGI server
• jinja2 - Template engine
• requests - HTTP client for MiniMax API
• pillow - Image processing
• aiofiles - Async file operations

No Redis or external services required; all state is in-memory or SQLite.