rehearshalhub/DEVELOPMENT_TASKS_OPTIMIZATION.md

# Development Tasks Optimization Summary

## Overview
Comprehensive optimization of the development workflow to reduce Docker overhead, preserve network/proxy configuration, and streamline the development process.

## Changes Made

### 1. Docker Configuration Fixes
**File**: `docker-compose.dev.yml`
- ✅ Changed `target: production` to `target: development` for both api and web services
- **Impact**: Enables hot reload and development-specific features

### 2. Streamlined Task Structure
**File**: `Taskfile.yml`

#### New Task Structure:
```bash
dev:up          # Main development task (recommended)
dev:build       # Explicit container building
dev:clean       # Safe cleanup (preserves network)
dev:nuke        # Full cleanup (when network corrupted)
dev:restart     # Quick service restart
dev:help        # Task documentation
```

#### Removed Redundant Tasks:
- `dev:full` → Replaced with `dev:up`
- `dev:audio-debug` → Use `dev:up` with debug env vars
- Conflicting frontend server management

### 3. Optimized Development Tasks

#### `dev:up` - Main Development Task
```yaml
dev:up:
  desc: Start complete development server (recommended)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} up -d {{.DEV_SERVICES}}"
    - "{{.COMPOSE}} {{.DEV_FLAGS}} logs -f api web audio-worker nc-watcher"
```
- **Benefits**: Single command to start everything, follows logs
- **Usage**: `task dev:up`

#### `dev:build` - Smart Building
```yaml
dev:build:
  desc: Build development containers (only when dependencies change)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} build --pull api web"
```
- **Benefits**: Explicit build step, uses `--pull` for latest base images
- **Usage**: `task dev:build` (run when dependencies change)

#### `dev:clean` - Safe Cleanup
```yaml
dev:clean:
  desc: Safe cleanup (preserves network/proxy, removes containers/volumes)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} down"
    - docker volume rm -f $(docker volume ls -q | grep rehearsalhub) || true
```
- **Benefits**: Preserves network/proxy configuration
- **Usage**: `task dev:clean`

#### `dev:nuke` - Full Cleanup
```yaml
dev:nuke:
  desc: Full cleanup (removes everything including network - use when network is corrupted)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} down -v"
    - docker system prune -f --volumes
```
- **Benefits**: Complete cleanup when network issues occur
- **Usage**: `task dev:nuke` (rarely needed)

### 4. Audio Service Enhancements
**File**: `web/src/services/audioService.ts`
- ✅ Added development mode detection with automatic debug logging
- ✅ Development-specific WaveSurfer configuration
- ✅ Better audio context management

## Workflow Recommendations

### Daily Development
```bash
# Start development (first time or after clean)
task dev:up

# Make code changes (hot reload works automatically)
# ... edit files ...

# When done
task dev:clean
```

### When Dependencies Change
```bash
# Rebuild containers
task dev:build
task dev:up
```

### When Network Issues Occur
```bash
# Full cleanup and restart
task dev:nuke
task dev:up
```

## Benefits Achieved

### ✅ Reduced Docker Overhead
- **Smart Building**: Only rebuild when necessary
- **Layer Caching**: Docker uses built-in layer caching
- **Minimal Downloads**: `--pull` only updates base images when needed

### ✅ Reliable Networking
- **Network Preservation**: `dev:clean` preserves proxy network
- **Safe Cleanup**: No accidental network destruction
- **Explicit Control**: `dev:nuke` for when network is truly corrupted

### ✅ Simpler Workflow
- **Clear Recommendations**: `dev:up` is the main task
- **Logical Separation**: Build vs run vs cleanup
- **Better Documentation**: `task help` shows all options

### ✅ Better Development Experience
- **Hot Reload**: Development targets enable live reloading
- **Debugging**: Automatic debug mode detection
- **Quick Restarts**: `dev:restart` for fast iteration

## Performance Comparison

### Before Optimization
- ❌ Frequent full rebuilds
- ❌ Network destruction on cleanup
- ❌ Confusing task structure
- ❌ Production targets in development
- ❌ No clear workflow recommendations

### After Optimization
- ✅ Smart incremental builds
- ✅ Network preservation
- ✅ Streamlined task structure
- ✅ Proper development targets
- ✅ Clear workflow documentation

## Migration Guide

### For Existing Developers
1. **Clean up old environment**:
   ```bash
   task dev:nuke  # Only if you have network issues
   ```

2. **Start fresh**:
   ```bash
   task dev:up
   ```

3. **Update your workflow**:
   - Use `dev:up` instead of `dev:full`
   - Use `dev:build` when you change dependencies
   - Use `dev:clean` for normal cleanup

### For New Developers
1. **Start development**:
   ```bash
   task dev:up
   ```

2. **See available tasks**:
   ```bash
   task help
   ```

3. **Clean up when done**:
   ```bash
   task dev:clean
   ```

## Troubleshooting

### Audio Playback Issues
- Ensure you're using `dev:up` (development targets)
- Check browser console for WebAudio errors
- Use `task dev:build` if you've changed audio dependencies

### Network/Proxy Issues
- Try `dev:clean` first (preserves network)
- If still broken, use `dev:nuke` (full cleanup)
- Check that proxy network exists: `docker network ls | grep proxy`

### Build Issues
- Run `dev:build` explicitly when dependencies change
- Check Docker layer caching with `docker system df`
- Use `--no-cache` if needed: `docker compose build --no-cache`

## Future Enhancements

### Potential Improvements
1. **Automatic Rebuild Detection**: Watch dependency files and auto-rebuild
2. **Cache Mounts**: Use Docker build cache mounts for even faster builds
3. **Multi-stage Optimization**: Further optimize Dockerfile layer ordering
4. **Task Aliases**: Add shortcuts like `task up` → `task dev:up`
5. **Environment Validation**: Auto-check for required tools and configs