refactor: remove server mode, router mode is now the only runtime path

.cascade/ensure-services.sh

@@ -91,4 +91,42 @@ if pg_isready -q 2>/dev/null; then
   fi
 fi
 
+# Redis check and restart (required for router mode / BullMQ job queue)
+if redis-cli ping 2>/dev/null | grep -q PONG; then
+  echo "Redis: running"
+else
+  echo "Redis: down - attempting restart..."
+
+  if command -v brew &>/dev/null; then
+    brew services start redis 2>/dev/null || true
+  elif command -v service &>/dev/null; then
+    sudo service redis-server start 2>/dev/null || \
+      redis-server --daemonize yes 2>/dev/null || true
+  elif command -v redis-server &>/dev/null; then
+    redis-server --daemonize yes 2>/dev/null || true
+  fi
+
+  # Wait for Redis to be ready
+  for i in {1..10}; do
+    if redis-cli ping 2>/dev/null | grep -q PONG; then
+      break
+    fi
+    echo "Waiting for Redis... ($i/10)"
+    sleep 1
+  done
+
+  # Final check
+  if redis-cli ping 2>/dev/null | grep -q PONG; then
+    echo "Redis: restarted successfully"
+  else
+    echo "Redis: FAILED TO START"
+    echo ""
+    echo "Troubleshooting:"
+    echo "  - Install Redis: brew install redis (macOS) or apt-get install redis-server (Linux)"
+    echo "  - Start manually: redis-server"
+    echo "  - Note: Redis is required for router mode (BullMQ job queue)"
+    exit 1
+  fi
+fi
+
 echo "=== All services running ==="

.cascade/env

@@ -2,3 +2,4 @@ CI=true
 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/cascade
 DATABASE_SSL=false
 TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/cascade_test
+REDIS_URL=redis://localhost:6379

.cascade/setup.sh

@@ -297,12 +297,82 @@ else
   log_warn "PostgreSQL not ready, skipping migrations"
 fi
 
+# =============================================================================
+# 6. Redis Setup (required for router mode / BullMQ job queue)
+# =============================================================================
+echo ""
+echo "--- Redis Setup ---"
+
+start_redis_macos() {
+  if command -v brew &> /dev/null; then
+    if ! brew list redis &> /dev/null; then
+      log_info "Redis not installed, installing..."
+      brew install redis
+    fi
+    log_info "Starting Redis..."
+    brew services start redis 2>/dev/null || true
+    # Wait for Redis to be ready
+    for i in {1..10}; do
+      if redis-cli ping 2>/dev/null | grep -q PONG; then
+        break
+      fi
+      log_info "Waiting for Redis... ($i/10)"
+      sleep 1
+    done
+  else
+    log_error "Homebrew not found on macOS. Please install Redis manually."
+    return 1
+  fi
+}
+
+start_redis_linux() {
+  if ! command -v redis-server &> /dev/null; then
+    log_info "Redis not installed, installing..."
+    if command -v apt-get &> /dev/null; then
+      sudo apt-get update && sudo apt-get install -y redis-server
+    else
+      log_error "Cannot install Redis - apt-get not available"
+      return 1
+    fi
+  fi
+
+  # Start Redis if not running
+  if ! redis-cli ping 2>/dev/null | grep -q PONG; then
+    log_info "Starting Redis..."
+    sudo service redis-server start 2>/dev/null || \
+      redis-server --daemonize yes 2>/dev/null || true
+    # Wait for Redis to be ready
+    for i in {1..10}; do
+      if redis-cli ping 2>/dev/null | grep -q PONG; then
+        break
+      fi
+      log_info "Waiting for Redis... ($i/10)"
+      sleep 1
+    done
+  fi
+}
+
+case "$OS" in
+  macos) start_redis_macos ;;
+  linux) start_redis_linux ;;
+  *) log_warn "Unknown OS, skipping Redis auto-start" ;;
+esac
+
+# Verify Redis is running
+if redis-cli ping 2>/dev/null | grep -q PONG; then
+  log_info "Redis is running"
+else
+  log_warn "Redis failed to start — router mode requires Redis for BullMQ job queue"
+  log_warn "Run 'redis-server' manually or install Redis before using 'npm run dev'"
+fi
+
 # =============================================================================
 # Summary
 # =============================================================================
 echo ""
 echo "=== CASCADE Setup Complete ==="
 echo "OS: $OS"
 echo "PostgreSQL: $(pg_isready 2>&1 || echo 'not running')"
+echo "Redis: $(redis-cli ping 2>/dev/null || echo 'not running')"
 echo "Node: $(node --version)"
 echo "npm: $(npm --version)"

.env.example

@@ -13,6 +13,12 @@ OPENROUTER_API_KEY=
 PORT=3000
 LOG_LEVEL=info
 
+# Redis — required for router mode (BullMQ job queue for webhook processing)
+# Run: brew install redis && brew services start redis (macOS)
+#      apt-get install redis-server && service redis-server start (Linux)
+# The .cascade/setup.sh script installs and starts Redis automatically.
+REDIS_URL=redis://localhost:6379
+
 # Optional: Path to projects config file
 # CONFIG_PATH=./config/projects.json
 

CLAUDE.md

@@ -5,22 +5,32 @@
 ```bash
 npm install
 cd web && npm install && cd ..
-npm run dev          # Backend
+# Start Redis (required for router/BullMQ):
+#   macOS: brew install redis && brew services start redis
+#   Linux: apt-get install redis-server && service redis-server start
+# The .cascade/setup.sh script handles this automatically.
+npm run dev          # Router (webhook receiver, requires Redis)
 npm run dev:web      # Dashboard frontend (separate terminal)
 ```
 
 ## Architecture
 
-CASCADE reacts to Trello webhooks and runs AI agents to analyze, plan, and implement features.
+CASCADE runs as three services (no monolithic server mode):
+
+1. **Router** (`src/router/index.ts`) — receives webhooks, enqueues jobs to Redis via BullMQ
+2. **Worker** (`src/worker-entry.ts`) — processes one job per container, exits when done
+3. **Dashboard** (`src/dashboard.ts`) — API + tRPC for web UI and CLI
 
 ### Trigger System
 
 The extensible trigger system routes events to agents:
 
 ```
-Trello/GitHub Webhook → TriggerRegistry → Agent → Code Changes → PR
+Trello/GitHub Webhook → Router → Redis/BullMQ → Worker → TriggerRegistry → Agent → Code Changes → PR
 ```
 
+- `src/router/` - Webhook receiver (enqueues jobs to Redis)
+- `src/webhook/` - Shared webhook handler factory, parsers, and logging
 - `src/triggers/` - Event handlers (Trello card moves, labels, GitHub PRs, attachments)
 - `src/agents/` - AI agents (splitting, planning, implementation, review, debug)
 - `src/gadgets/` - Tools agents can use (Trello API, Git operations, file system)
@@ -53,6 +63,8 @@ Lefthook runs pre-commit (lint, typecheck) and pre-push (test) hooks automatical
 
 ## Key Directories
 
+- `src/router/` - Router entry point (webhook receiver, enqueues to Redis)
+- `src/webhook/` - Shared webhook handler factory, parsers, and logging helpers
 - `src/config/` - Configuration provider, caching, Zod schemas
 - `src/db/` - Database client, Drizzle schema, repositories
 - `src/triggers/` - Extensible trigger system (Trello, GitHub)
@@ -70,6 +82,7 @@ Lefthook runs pre-commit (lint, typecheck) and pre-push (test) hooks automatical
 
 Required:
 - `DATABASE_URL` - PostgreSQL connection string (Supabase transaction pooler, port 6543)
+- `REDIS_URL` - Redis connection string for BullMQ job queue (router + worker). Defaults to `redis://localhost:6379`. Run `.cascade/setup.sh` to install and start Redis locally.
 
 Optional (infrastructure):
 - `PORT` - Server port (default: 3000)

README.md

@@ -19,6 +19,7 @@ Multi-project Trello-to-code automation platform. CASCADE reacts to Trello card
 - npm
 - Git
 - GitHub CLI (`gh`) - for PR creation
+- Redis (required for router mode / BullMQ job queue)
 
 ### Installation
 
@@ -169,13 +170,23 @@ npm run build
 npm start
 ```
 
+### Architecture
+
+CASCADE runs as three services:
+
+1. **Router** (`src/router/index.ts`) — receives webhooks, enqueues jobs to Redis via BullMQ
+2. **Worker** (`src/worker-entry.ts`) — processes one job per container, exits when done
+3. **Dashboard** (`src/dashboard.ts`) — API + tRPC for web UI and CLI
+
 ### Project Structure
 
 ```
 cascade/
 ├── src/
-│   ├── index.ts              # Entry point
-│   ├── server.ts             # Hono HTTP server
+│   ├── router/               # Router entry point (webhook receiver)
+│   ├── worker-entry.ts       # Worker entry point (job processor)
+│   ├── dashboard.ts          # Dashboard entry point (API + tRPC)
+│   ├── webhook/              # Shared webhook handler factory + parsers
 │   ├── config/               # Configuration loading & validation
 │   ├── triggers/             # Extensible trigger system
 │   │   ├── registry.ts       # TriggerRegistry

package.json

@@ -3,15 +3,15 @@
 	"version": "1.0.0",
 	"description": "Trello-to-Code Automation Platform - Reacts to Trello card movements and collaborates like a dev team",
 	"type": "module",
-	"main": "dist/index.js",
+	"main": "dist/router/index.js",
 	"scripts": {
-		"dev": "node --env-file=.env --import tsx/esm --watch src/index.ts",
+		"dev": "node --env-file=.env --import tsx/esm --watch src/router/index.ts",
 		"dev:web": "cd web && npx vite",
 		"build": "tsc && npm run build:copy-yaml && npm run build:copy-system-prompts",
 		"build:copy-yaml": "mkdir -p dist/agents/definitions && cp src/agents/definitions/*.yaml dist/agents/definitions/",
 		"build:copy-system-prompts": "mkdir -p dist/agents/prompts && cp -r src/agents/prompts/templates dist/agents/prompts/",
 		"build:web": "cd web && npm run build",
-		"start": "node dist/index.js",
+		"start": "node dist/router/index.js",
 		"test": "vitest run --project unit",
 		"test:unit": "vitest run --project unit",
 		"test:integration": "vitest run --project integration",