From 241dd24a221405389f0636cef7c3e6e143253497 Mon Sep 17 00:00:00 2001
From: Mistral Vibe <vibe@mistral.ai>
Date: Wed, 8 Apr 2026 15:40:27 +0200
Subject: [PATCH] docs: add comprehensive documentation for optimized
 development tasks

---
 DEVELOPMENT_TASKS_OPTIMIZATION.md | 206 ++++++++++++++++++++++++++++++
 1 file changed, 206 insertions(+)
 create mode 100644 DEVELOPMENT_TASKS_OPTIMIZATION.md

diff --git a/DEVELOPMENT_TASKS_OPTIMIZATION.md b/DEVELOPMENT_TASKS_OPTIMIZATION.md
new file mode 100644
index 0000000..39b01a4
--- /dev/null
+++ b/DEVELOPMENT_TASKS_OPTIMIZATION.md
@@ -0,0 +1,206 @@
+# 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
\ No newline at end of file