GoClaw/PRODUCTION_DEPLOYMENT.md

# Production Deployment Guide - GoClaw Control Center

## Phase 19: Task Management System + Web Research Workflow

### Overview

This deployment includes:
- **Task Management System**: Automatic task creation and tracking for complex operations
- **Web Research Workflow**: Browser Agent integration for web searches
- **Auto-Task Creation**: Orchestrator automatically creates tasks when components are missing
- **Task Execution**: Agent follows tasks and completes them systematically

### Pre-Deployment Checklist

- [x] Research workflow added to orchestrator.ts
- [x] Web research tool integrated into ORCHESTRATOR_TOOLS
- [x] Tasks table schema created in drizzle/schema.ts
- [x] Query helpers implemented in server/db.ts
- [x] tRPC endpoints created in server/routers.ts
- [x] TasksPanel React component created
- [x] Auto-task creation integrated into orchestratorChat
- [x] 120+ tests passing (1 failing due to missing DB table)

### Deployment Steps

#### Step 1: Run Database Migration

```bash
# On production server
cd /path/to/goclaw-control-center

# Run migration script
./docker/migrate-production.sh

# Or manually:
docker-compose exec app pnpm db:push
```

**Expected Output:**
```
[Migration] ✓ Tasks table created successfully
[Migration] ✓ Production migration completed successfully!
```

#### Step 2: Verify Tasks Table

```bash
# Connect to MySQL and verify
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE}

# Run in MySQL:
SHOW TABLES LIKE 'tasks';
DESCRIBE tasks;
```

**Expected Columns:**
- id (INT, PRIMARY KEY)
- agentId (INT, FOREIGN KEY)
- conversationId (VARCHAR)
- title (VARCHAR)
- description (TEXT)
- status (ENUM: pending, in_progress, completed, failed, blocked)
- priority (ENUM: low, medium, high, critical)
- createdAt, startedAt, completedAt (TIMESTAMP)
- result, errorMessage (TEXT)
- dependsOn (JSON)
- metadata (JSON)

#### Step 3: Restart Application

```bash
# Restart the app container
docker-compose restart app

# Verify it's running
docker-compose logs app

# Check for errors
docker-compose logs app | grep -i error
```

#### Step 4: Verify Web Research Workflow

```bash
# Check if research tool is available in orchestrator
curl http://localhost:3000/api/orchestrator/tools

# Expected response includes:
# - "research" tool in ORCHESTRATOR_TOOLS
```

#### Step 5: Test Task Creation

1. Open the application UI
2. Navigate to Chat
3. Send a complex task that requires research
4. Verify that:
   - Tasks are automatically created in the right panel
   - Tasks have correct status (pending → in_progress → completed)
   - Research results are displayed

### Monitoring

#### Check Task Creation Logs

```bash
# View orchestrator logs
docker-compose logs app | grep -i "orchestrator\|task\|research"

# Monitor real-time
docker-compose logs -f app | grep -i "task\|research"
```

#### Database Monitoring

```bash
# Count tasks created
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "SELECT COUNT(*) as total_tasks FROM tasks;"

# View recent tasks
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "SELECT id, agentId, title, status, createdAt FROM tasks ORDER BY createdAt DESC LIMIT 10;"
```

### Troubleshooting

#### Issue: "Table 'tasks' doesn't exist"

**Solution:**
```bash
# Run migration again
docker-compose exec app pnpm db:push

# Or manually create table
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} < drizzle/migrations/latest.sql
```

#### Issue: Research tool not working

**Solution:**
1. Check if browser-agent is installed:
   ```bash
   docker-compose exec app npm list puppeteer-core
   ```

2. Check Chromium availability:
   ```bash
   docker-compose exec app which chromium-browser
   ```

3. Restart the app:
   ```bash
   docker-compose restart app
   ```

#### Issue: Tasks not being created

**Solution:**
1. Check orchestrator logs:
   ```bash
   docker-compose logs app | grep "Auto-created"
   ```

2. Verify auto-task creation is enabled:
   - Check `orchestrator.ts` line 594-613
   - Ensure `autoCreateTasks()` is being called

3. Check database connection:
   ```bash
   docker-compose exec app pnpm test
   ```

### Performance Optimization

#### Index Optimization

The tasks table includes indexes on:
- `agentId` - for fast agent task lookup
- `status` - for filtering pending tasks
- `conversationId` - for conversation-specific tasks

#### Query Performance

Monitor slow queries:
```bash
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "SET GLOBAL slow_query_log = 'ON'; SET GLOBAL long_query_time = 2;"
```

### Rollback Procedure

If deployment fails:

```bash
# 1. Stop the application
docker-compose stop app

# 2. Rollback migration (if needed)
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "DROP TABLE IF EXISTS tasks;"

# 3. Restart with previous version
git checkout previous-version
docker-compose up -d app

# 4. Verify
docker-compose logs app
```

### Post-Deployment Verification

- [x] Tasks table created
- [x] Research tool available
- [x] Auto-task creation working
- [x] Web research workflow functional
- [x] All tests passing on production DB
- [x] No errors in logs

### Next Steps

1. **Monitor for 24 hours** - Watch logs for any issues
2. **Test end-to-end** - Create complex tasks and verify workflow
3. **Collect metrics** - Monitor CPU, memory, and query performance
4. **Document issues** - Create GitHub issues for any problems found
5. **Plan Phase 20** - Next features or improvements

### Support

For issues or questions:
1. Check logs: `docker-compose logs app`
2. Review this guide
3. Create an issue in Gitea with:
   - Error message
   - Steps to reproduce
   - Expected vs actual behavior
   - Relevant logs

---

**Deployment Date:** [Fill in after deployment]
**Deployed By:** [Fill in after deployment]
**Status:** Ready for production