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! 🎉