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

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

### Backend API Docs

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

### Frontend

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

### Database Connection

```bash
# 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

```bash
# 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

```bash
cd backend

# Type checking
mypy app

# Linting
ruff check app

# Formatting
black --check app

# Tests
pytest tests/ -v
```

### Frontend

```bash
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:**
```bash
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:

```bash
# 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! 🎉