← back to Designer Wallcoverings

DW-Agents/CLAUDE.md

383 lines

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## ⚠️ CRITICAL OPERATIONAL REQUIREMENTS ⚠️

**THE FOLLOWING ARE NON-NEGOTIABLE REQUIREMENTS:**

1. **ALL AGENTS MUST BE RUNNING 24/7** - Zero tolerance for agent downtime
2. **MONITOR EVERY 10 MINUTES** - Automated health checks must run continuously
3. **AUTO-RESTART IF DOWN** - Any stopped agent must restart immediately
4. **INTERVENTION AT 20 RESTARTS** - Automatically analyze logs, fix errors, and force restart
5. **NEVER LEAVE AGENTS DOWN** - If an agent is down, fixing it is the #1 priority

**Required Monitoring Setup:**
```bash
# This cron job MUST be active:
*/10 * * * * /root/Projects/Designer-Wallcoverings/DW-Agents/scripts/agent-health-monitor.sh
```

**If ANY agent is down or has >20 restarts:**
1. Stop everything else you're doing
2. Analyze the logs immediately
3. Fix the root cause
4. Restart the agent
5. Verify it stays running

## Project Overview

DW-Agents is a comprehensive multi-agent AI system for Designer Wallcoverings business operations. Built with TypeScript, Node.js, Express, and Anthropic's Claude AI, the system consists of 30+ specialized agents handling different business functions including marketing, accounting, customer service, and executive dashboards.

## Architecture & Code Structure

### Technology Stack
- **Runtime**: Node.js with TypeScript (tsx)
- **Framework**: Express.js for all agent servers
- **Process Manager**: PM2 for production deployment
- **AI Integration**: Anthropic Claude API
- **Authentication**: Session-based with admin/2025 credentials
- **Ports**: Each agent runs on a unique port (7000-9999 range)

### Directory Structure
```
/root/Projects/Designer-Wallcoverings/DW-Agents/
├── dw-agents/              # All agent implementations
│   ├── agent-{name}/       # Individual agent directories
│   ├── shared-*.ts         # Shared components and utilities
│   └── *.ts               # Agent main files
├── scripts/                # Operational scripts
├── logs/                   # Centralized logging
├── data/                   # Persistent data storage
├── __tests__/              # Test suite
└── ecosystem.config.js     # PM2 configuration
```

### Agent Architecture Pattern
Every agent follows a consistent architecture:
- Express server with authentication middleware
- Chat integration via shared components
- Memory system for persistent state
- Hooks API for inter-agent communication
- Standardized UI components
- Health check endpoints

## Critical Commands

### Agent Operations
```bash
# Start all agents
pm2 start ecosystem.config.js

# Check agent status and restart counts
pm2 list | grep dw-

# View logs for specific agent
pm2 logs dw-{agent-name}

# Monitor all agents in real-time
pm2 monit

# Restart specific agent
pm2 restart dw-{agent-name}

# Check for excessive restarts (>20 is critical)
for app in $(pm2 jlist | jq -r '.[] | select(.pm2_env.restart_time > 20) | .name'); do
  echo "CRITICAL: $app has excessive restarts"
  pm2 logs $app --err --lines 50
done

# Setup auto-start after system reboot
pm2 startup
pm2 save
```

### Health Monitoring
```bash
# Run health monitor script (checks one agent every 2 minutes)
/root/Projects/Designer-Wallcoverings/DW-Agents/scripts/agent-health-monitor.sh

# Check agent health endpoint
curl http://45.61.58.125:{PORT}/api/health

# View health monitor logs
tail -f /root/Projects/Designer-Wallcoverings/DW-Agents/logs/health-monitor.log
```

### Testing
```bash
# Run all tests with coverage
npm test

# Run specific test suites
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests
npm run test:e2e           # End-to-end tests
npm run test:health        # Health check tests

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run coverage
```

### Development
```bash
# Run agent locally for testing
cd dw-agents
PORT=9880 npx tsx {agent-name}.ts

# Check port availability
lsof -ti:{PORT}

# Kill process on port
lsof -ti:{PORT} | xargs kill -9

# Open firewall port
sudo ufw allow {PORT}/tcp

# Check firewall status
sudo ufw status numbered
```

## Critical Requirements

### MANDATORY: Continuous Agent Availability
- **ALL agents must ALWAYS be running** - Zero tolerance for downtime
- **Automatic restart if down** - PM2 configured to restart immediately on failure
- **Monitor every 10 minutes** - Automated health checks must run continuously
- **Crash loop intervention at 20 restarts** - Automatic log analysis, error fixing, and restart
- **System reboot recovery** - PM2 startup ensures agents restart after any system reboot
- **Firewall ports open** - All agent ports must be accessible externally

### Automated Monitoring (EVERY 10 MINUTES)
```bash
# Add to crontab for 10-minute monitoring
*/10 * * * * /root/Projects/Designer-Wallcoverings/DW-Agents/scripts/agent-health-monitor.sh

# Monitor and auto-fix script that MUST run continuously
#!/bin/bash
# This script MUST:
# 1. Check all agents are running
# 2. Restart any stopped agents
# 3. If restarts > 20: analyze logs, fix errors, force restart
# 4. Log all interventions
```

### Automatic Recovery Process (MUST BE IMPLEMENTED)

**When Any Agent Exceeds 20 Restarts - AUTOMATIC INTERVENTION REQUIRED:**
1. **Immediately stop the problematic agent**: `pm2 stop {agent}`
2. **Analyze error logs**: `pm2 logs {agent} --err --lines 100`
3. **Apply automatic fixes in this order**:
   - Clear port conflicts: `lsof -ti:{PORT} | xargs kill -9`
   - Clear stuck processes: `pkill -f {agent}`
   - Increase memory if needed: Update `max_memory_restart` in ecosystem.config.js
   - Reinstall dependencies: `cd /root/Projects/Designer-Wallcoverings/DW-Agents && npm install`
   - Clear temp files: `find /tmp -name "*{agent}*" -type f -delete`
4. **Force reset and restart**: 
   ```bash
   pm2 delete {agent}
   pm2 start ecosystem.config.js --only {agent}
   pm2 save
   ```
5. **Verify recovery**: Check status after 30 seconds
6. **Log intervention**: Record all actions taken in `/logs/recovery.log`

**Port Conflicts**
```bash
# Find and kill process on port
lsof -ti:{PORT} | xargs kill -9

# Verify port is free
netstat -tulnp | grep {PORT}
```

**Authentication Issues**
- Clear browser cookies
- Verify credentials: admin/2025
- Check session middleware in agent code

## Key Agents & Ports

### Core System
- **Master Hub** (9893) - Central control panel
- **Agent Control Panel** (7200) - Advanced monitoring
- **Dashboard Monitor** (9990) - System overview
- **Crash Loop Resolver** (9895) - Auto-recovery system

### Executive Dashboards
- **CEO Dashboard** (7120)
- **CFO Dashboard** (7121)
- **COO Dashboard** (7122)
- **VP-Ops Dashboard** (7123)

### Business Operations
- **Digital Samples** (9879) - Shopify DIG-series orders
- **Legal Team** (9878) - Settlement compliance
- **Purchasing Office** (9880) - Vendor management
- **Marketing** (9881) - Campaign management
- **Accounting** (9882) - Financial monitoring
- **Trend Research** (9883) - Market analysis

### Customer Service
- **Zendesk Chat** (9884) - Support integration
- **Shopify Store** (7238) - E-commerce operations

### System Monitoring
- **Log Monitor** (7239) - Log aggregation
- **UI Manager** (7240) - Interface management
- **Needs Attention** (9886) - Priority alerts

## Shared Components

### Authentication (`shared-auth.ts`, `shared-global-auth.ts`)
- Session-based authentication
- Default credentials: admin/2025
- Cookie-based session management

### Chat System (`shared-chat.ts`, `shared-chat-integration.ts`)
- Anthropic Claude integration
- Unified chat interface across all agents
- Memory-aware conversations

### Memory System (`shared-memory-system.ts`)
- Persistent JSON storage per agent
- Categories: note, reminder, preference, learning, conversation, task
- Auto-save on changes

### Inter-Agent Communication (`shared-hooks-api.ts`)
- Webhook registration and notification
- Event-driven architecture
- Task distribution via orchestrator

### UI Components (`shared-ui-components.js`)
- Consistent dashboard styling
- Dark theme support
- Responsive design

## Adding New Agents

1. Create agent directory:
```bash
mkdir dw-agents/agent-{name}
```

2. Copy template structure from existing agent

3. Add to ecosystem.config.js:
```javascript
{
  name: 'dw-{name}',
  script: 'npx',
  args: 'tsx {name}-agent.ts',
  cwd: '/root/Projects/Designer-Wallcoverings/DW-Agents/dw-agents',
  env: {
    NODE_ENV: 'production',
    PORT: {unique-port},
    NODE_OPTIONS: '--import tsx'
  }
}
```

4. Open firewall port:
```bash
sudo ufw allow {PORT}/tcp
```

5. Start agent:
```bash
pm2 start ecosystem.config.js --only dw-{name}
```

## Environment Variables

Configured in ecosystem.config.js per agent:
- `ANTHROPIC_API_KEY` - AI capabilities
- `SHOPIFY_STORE_DOMAIN` - E-commerce integration
- `SHOPIFY_ACCESS_TOKEN` - Store API access
- `SLACK_BOT_TOKEN` - Slack notifications
- `ZENDESK_*` - Support system credentials

## Database & Storage

- **Tasks**: `dw-agents/tasks-database.json`
- **Agent Memory**: `dw-agents/agent-{name}/memory.json`
- **Logs**: `/root/Projects/Designer-Wallcoverings/DW-Agents/logs/`
- **Reports**: `dw-agents/reports/`
- **Data**: `/root/Projects/Designer-Wallcoverings/DW-Agents/data/`

## Critical Business Logic

### Digital Samples Agent
- Processes DIG-series orders from Shopify
- Image resizing with Sharp library
- Manual approval workflow before customer delivery

### Legal Team Agent
- Settlement compliance monitoring
- Tropical design violation detection
- Product catalog auditing

### Executive Dashboards
- Real-time KPI tracking
- Business intelligence reporting
- Strategic metric visualization

## Performance Requirements

- Health check response: <100ms (P95)
- API response: <200ms (P95)
- Throughput: >100 req/s sustained
- Concurrent connections: 50+ stable
- Memory limit: 300-500MB per agent
- Restart threshold: <20 restarts before investigation

## Monitoring & Alerting

### Automated Monitoring
- Health monitor script runs via cron every 2 minutes
- Rotates through agents checking one per run
- Auto-fixes problematic agents
- Logs to `/logs/health-monitor.log`

### Manual Health Checks
```bash
# Check all agent statuses
pm2 list

# Check specific agent health
curl http://45.61.58.125:{PORT}/api/health

# View recent errors
pm2 logs --err --lines 100

# Check system resources
free -h && df -h
```

## Testing Strategy

### Test Coverage Requirements
- Branches: 70%
- Functions: 70%
- Lines: 70%
- Statements: 70%

### Test Categories
- **Unit**: Individual functions and utilities
- **Integration**: API endpoints and services
- **E2E**: Complete workflows
- **Health**: Endpoint availability and performance
- **Performance**: Load and stress testing

## Security Considerations

- All agents require authentication (admin/2025)
- Session cookies with secure flags
- CORS configured for known origins
- No sensitive data in logs
- API keys stored in environment variables
- Firewall rules restrict to necessary ports only
- All agents must always restat if down and if restarts over 20, analyze logs, fix errors, restart. All agents should always be live and monitored every 10 minutes.