VERIFICATION.md

AudioForge Setup Verification Checklist

Use this checklist to verify your AudioForge installation is correct and ready to run.

✅ Pre-Flight Checks

Backend

• Python 3.11+ installed (python --version)
• Virtual environment created and activated
• Dependencies installed (uv pip install -e ".[dev]")
• .env file exists (copied from .env.example)
• Storage directories exist (storage/audio/{music,vocals,mixed,mastered})
• PostgreSQL running and accessible
• Redis running (optional but recommended)
• Database initialized (python scripts/init_db.py)

Frontend

• Node.js 20+ installed (node --version)
• Dependencies installed (pnpm install)
• .env.local exists with NEXT_PUBLIC_API_URL
• No build errors (pnpm build succeeds)

✅ Runtime Checks

Backend Health

# Should return: {"status":"healthy","version":"0.1.0"}
curl http://localhost:8000/health

Backend API Docs

# Should open Swagger UI
open http://localhost:8000/api/docs

Frontend

# Should open AudioForge interface
open http://localhost:3000

Database Connection

# Backend should connect without errors
# Check logs for: "database_initialized_successfully"

✅ Functional Tests

Test Generation Flow

1. Open http://localhost:3000
2. Enter prompt: "A calm acoustic guitar melody"
3. Click "Generate Music"
4. See generation status change: pending → processing → completed
5. Audio file generated and playable

Test API Directly

# Create generation
curl -X POST http://localhost:8000/api/v1/generations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Test music generation"}'

# Should return generation ID and status: "pending"

✅ Code Quality Checks

Backend

cd backend

# Type checking
mypy app

# Linting
ruff check app

# Formatting
black --check app

# Tests
pytest tests/ -v

Frontend

cd frontend

# Type checking
pnpm type-check

# Linting
pnpm lint

# Tests
pnpm test

✅ Performance Checks

• Backend starts in < 5 seconds
• Frontend builds in < 30 seconds
• API responses < 100ms (excluding generation)
• No memory leaks (check with docker stats)

✅ Security Checks

• .env not committed to git
• SECRET_KEY changed from default
• CORS configured correctly
• No sensitive data in logs

✅ Documentation Checks

• README.md complete
• SETUP.md complete
• ARCHITECTURE.md complete
• API docs accessible
• Code comments present

Common Issues & Solutions

Issue: Backend won't start

Check:

cd backend
python scripts/verify_setup.py

Common causes:

• Missing dependencies → uv pip install -e ".[dev]"
• Database not running → docker-compose up -d postgres
• Port 8000 in use → Change port or stop conflicting service

Issue: Frontend won't connect to backend

Check:

• .env.local has correct NEXT_PUBLIC_API_URL
• Backend is running on correct port
• CORS allows frontend origin

Issue: Generation fails

Check:

• Models downloading (first time takes time)
• Sufficient disk space (~2GB for models)
• GPU/CUDA if using GPU mode
• Check backend logs for errors

Issue: Database errors

Check:

• PostgreSQL running: docker-compose ps or pg_isready
• DATABASE_URL correct in .env
• Database exists: createdb audioforge if needed
• Migrations applied: alembic upgrade head

Verification Script

Run automated verification:

# Backend
cd backend
python scripts/verify_setup.py

# Should show all ✅ checks

Production Readiness

Before deploying to production:

• All tests passing
• Environment variables configured
• Database migrations applied
• Storage configured (S3 or persistent volume)
• Monitoring set up
• Logging configured
• Security review completed
• Performance tested
• Documentation updated

Success Criteria

✅ All checks pass ✅ Backend responds to health check ✅ Frontend loads without errors ✅ Can create a generation ✅ Generation completes successfully ✅ Audio file is playable

If all checks pass, you're ready to go! 🎉