← back to Designer Wallcoverings

DW-Agents/dw-agents/CLAUDE.md

327 lines

# CLAUDE.md

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

## 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 that handle different business functions, from marketing and accounting to customer service and executive dashboards.

## DW-Agents Best Practices Guide

### 1. **Architecture & Code Structure**
- **Follow the established pattern**: Express + TypeScript + shared modules
- **Use shared components**: 
  - `shared-auth.ts` for authentication (admin/2025)
  - `shared-memory-system.ts` for persistent state
  - `shared-chat.ts` for AI integration
  - `shared-hooks-api.ts` for inter-agent communication
  - `shared-ui-components.js` for consistent UI
  - `shared-database.ts` for PostgreSQL access via Prisma
- **Directory structure**: Each agent in `agent-{name}/` folder with consistent files

### 2. **Database Strategy**
- **PostgreSQL** for shared business data (products, vendors, logs) via `shared-database.ts`
- **JSON files** for agent-specific memory/state via `AgentMemory` class
- **NO SQLite** - Migrate any SQLite usage to PostgreSQL for consistency
- **Use Prisma ORM** for type-safety and migrations
- **Connection string**: `postgresql://dw_admin:DW2025secure@127.0.0.1:5432/dw_unified`
- **Don't mix**: Keep business data in PostgreSQL, agent memory in JSON

### 3. **Uptime & Reliability**
- **ALL agents must run 24/7** - Business depends on continuous availability
- **Auto-restart on failure**: Configure PM2 with proper memory limits (300-500MB)
- **Monitor restart counts**: If >20 restarts, investigate immediately
- **Setup PM2 startup**: `pm2 startup` and `pm2 save` for system reboot recovery
- **Health endpoints**: Implement `/api/status` or `/api/health` for monitoring
- **Error handling**: Graceful degradation, don't crash on non-critical errors

### 4. **Port Management**
- **Unique ports only**: Never reuse ports
- **Port ranges**:
  - 9800-9999: DW-Agents
  - 7000-7999: Executive dashboards
  - 3000-3999: Special services
- **Open firewall immediately**: `sudo ufw allow {PORT}/tcp`
- **Check before starting**: `lsof -ti:{PORT}`
- **Document in ecosystem.config.js**: All ports must be defined there

### 5. **Memory Management**
- **Use AgentMemory class** from `shared-memory-system.ts`
- **Categories**: note, reminder, preference, learning, conversation, task
- **JSON validation**: Always validate before parsing memory.json
- **Atomic writes**: Use temp files to prevent corruption
- **Regular cleanup**: Implement memory pruning for old entries (>30 days)
- **Size limits**: Keep memory.json under 10MB per agent

### 6. **Error Handling & Monitoring**
- **PM2 logs**: Check with `pm2 logs dw-{agent} --err`
- **Crash loop detection**: Daily script to check restart counts
- **Common fixes**:
  - Port conflicts: `lsof -ti:PORT | xargs kill -9`
  - Memory issues: Increase max_memory_restart in ecosystem.config.js
  - Missing deps: `cd agent-{name} && npm install`
  - API keys: Check environment variables
  - JSON parsing: Add try-catch with fallback to empty data
- **Logging**: Use consistent format with timestamps and error levels

### 7. **Inter-Agent Communication**
- **Use hooks API**: Register webhooks at `/api/register-webhook`
- **Task orchestrator as hub**: Central task distribution
- **Event-driven**: Agents notify each other of important events
- **Avoid direct calls**: Use hooks system instead of direct HTTP calls
- **Timeout handling**: 5 second timeout for inter-agent requests

### 8. **Authentication & Security**
- **Session-based auth**: All agents require login (admin/2025)
- **Secure cookies**: Use express-session with secure settings
- **CORS configuration**: Allow cross-agent communication from known ports
- **Check middleware**: Always verify `req.session.authenticated`
- **SSO tokens**: Share authentication across agents

### 9. **Development & Testing**
```bash
# Development mode
PORT=9880 npx tsx agent-name.ts

# Test endpoint
curl -X GET http://45.61.58.125:9880/api/status

# Check health of all agents
/root/Projects/Designer-Wallcoverings/DW-Agents/agent-health-check.sh

# Monitor in real-time
pm2 monit
```

### 10. **Adding New Agents Checklist**
1. Create directory: `mkdir agent-{name}`
2. Copy template from existing agent
3. Update shared modules paths
4. Add to ecosystem.config.js with unique port
5. Open firewall port: `sudo ufw allow {PORT}/tcp`
6. Implement core interfaces (auth, health, hooks, memory)
7. Add memory.json initialization
8. Start with PM2: `pm2 start ecosystem.config.js --only dw-{name}`
9. Verify health endpoint works
10. Document in README.md

### 11. **Performance Optimization**
- **Cluster mode**: Use PM2 cluster for multi-core utilization
- **Memory limits**: Set appropriate max_memory_restart (300-500MB)
- **Log rotation**: Configure PM2 log management
- **Database pooling**: Connection pools handled by Prisma
- **Cache frequently**: Use memory.json for caching (5min TTL)
- **Async operations**: Use async/await properly, avoid blocking

### 12. **Deployment Checklist**
- [ ] All agents have health endpoints
- [ ] PM2 startup configured: `pm2 startup && pm2 save`
- [ ] Firewall ports open for all agents
- [ ] Environment variables set in ecosystem.config.js
- [ ] Error handling for JSON parsing
- [ ] Memory limits configured
- [ ] Logs rotating properly
- [ ] Database connections pooled
- [ ] Authentication working across agents
- [ ] Monitoring dashboard accessible

## CRITICAL REQUIREMENTS

### Agent Uptime & Availability
- **ALL agents must be running at all times** - Business operations depend on continuous agent availability
- **Auto-restart on system reboot** - Agents must automatically start after any system restart
- **Crash loop detection** - If an agent restarts more than 20 times, investigate and fix the root cause immediately
- **PM2 startup configuration** - Ensure `pm2 startup` and `pm2 save` are configured for automatic recovery
- **Firewall ports must be open** - All agent ports MUST have open firewall rules for external access

### Monitoring & Recovery
```bash
# Check agent restart counts
pm2 list | grep restart

# Monitor agents with high restart counts
pm2 describe dw-{agent-name} | grep restarts

# Setup PM2 to auto-start on system boot
pm2 startup
pm2 save

# Force restart all agents after system issues
pm2 restart ecosystem.config.js

# Check for crash loops (>20 restarts)
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
```

### Fixing Excessive Restarts
When an agent exceeds 20 restarts:
1. Check error logs: `pm2 logs {agent-name} --err --lines 100`
2. Common fixes:
   - Port conflicts: `lsof -ti:{PORT} | xargs kill -9`
   - Memory issues: Increase `max_memory_restart` in ecosystem.config.js
   - Missing dependencies: `cd /root/DW-Agents && npm install`
   - Permission issues: Check file permissions on agent directories
   - API key expiration: Verify environment variables in ecosystem.config.js
3. Reset the agent: `pm2 delete {agent-name} && pm2 start ecosystem.config.js --only {agent-name}`
4. Monitor recovery: `pm2 monit`

## Common Development Commands

### Running Agents
```bash
# Start all agents via PM2
pm2 start ecosystem.config.js

# View running agents
pm2 list | grep dw-

# Restart specific agent
pm2 restart dw-marketing

# View agent logs
pm2 logs dw-digital-samples

# Monitor real-time status
pm2 monit

# Stop all agents
pm2 stop all
```

### Development & Testing
```bash
# Run individual agent in development
PORT=9880 npx tsx purchasing-office-agent.ts

# Test agent endpoint
curl -X GET http://45.61.58.125:9880/api/status

# Check port availability
lsof -ti:9880

# Open firewall port for new agent
sudo ufw allow 9880/tcp

# Open firewall ports for all DW agents
for port in 9882 7677 9895 9990 9879 7120 7121 7122 7123 9881 9893 9886 9880 7238 9883 7240 9884 9878 7239; do
  sudo ufw allow $port/tcp
done
```

## Architecture & Code Structure

### Agent Architecture Pattern
All agents follow a consistent TypeScript/Express architecture:
- **Express server** with authentication middleware (admin/2025)
- **Chat integration** via shared-chat.ts and shared-chat-integration.ts
- **Memory system** via shared-memory-system.ts for persistent state
- **Hooks API** via shared-hooks-api.ts for inter-agent communication
- **UI components** via shared-ui-components.js for consistent dashboard styling
- **Task reporting** via shared-task-reporter.ts for orchestrator updates

### Key Shared Components

**Authentication & Security**
- `shared-auth.ts` / `shared-global-auth.ts` - Session-based auth system
- All agents require login (admin/2025) and use secure session cookies
- CORS configured for cross-agent communication

**Inter-Agent Communication**
- `shared-hooks-api.ts` - Webhook system for agent-to-agent messaging
- Agents can register webhooks and notify each other of events
- Task orchestrator acts as central hub for task distribution

**Memory & Persistence**
- `shared-memory-system.ts` - AgentMemory class for persistent storage
- Each agent maintains JSON memory file in agent-{name}/memory.json
- Memories categorized by type: note, reminder, preference, learning, conversation, task

**Chat System Integration**
- `shared-chat.ts` / `shared-chat-integration.ts` - Unified chat interface
- All agents integrate chat endpoints for AI interaction
- Anthropic Claude API integration for AI responses

### Agent Directory Structure
```
agent-{name}/
├── {name}-agent.ts    # Main agent file
├── README.md          # Agent documentation
├── memory.json        # Persistent memory
└── chat.html          # Chat interface (optional)
```

### PM2 Configuration
All agents configured in `ecosystem.config.js` with:
- Auto-restart on failure
- Memory limits (300-500MB)
- Log rotation and formatting
- Environment variables (ports, API keys)

## Adding New Agents

1. Create agent directory: `agent-{name}/`
2. Copy template structure from existing agent
3. Add to ecosystem.config.js with unique port
4. Open firewall port: `sudo ufw allow {PORT}/tcp`
5. Implement core interfaces (auth, chat, hooks, memory)
6. Start with PM2: `pm2 start ecosystem.config.js --only dw-{name}`

## Important Integration Points

### Master Hub (port 9893)
Central control panel that monitors all agents and provides unified access.

### Task Orchestrator (agent-task-orchestrator)
Manages task distribution and tracking across all agents. Uses tasks-database.json for persistence.

### Hooks API System
Agents communicate via webhooks registered at `/api/register-webhook` endpoints. Events flow through the hooks system for coordination.

### Authentication Flow
All agents use shared session-based auth with middleware checking `req.session.authenticated`.

## Environment Configuration

Key environment variables set in ecosystem.config.js:
- `ANTHROPIC_API_KEY` - Claude AI access
- `SHOPIFY_*` - Shopify store integration
- `SLACK_BOT_TOKEN` - Slack notifications
- `ZENDESK_*` - Customer support integration
- `PORT` - Each agent's unique port

## Database & Storage

- **Tasks**: `tasks-database.json` - Central task tracking
- **Agent Memory**: Individual `agent-{name}/memory.json` files
- **Logs**: Centralized in `/root/DW-Agents/logs/`
- **Reports**: Generated in `reports/` directory

## Testing & Debugging

### Common Issues & Solutions
- **Port conflicts**: Kill existing process with `lsof -ti:PORT | xargs kill -9`
- **Auth failures**: Clear session cookies and re-login
- **Memory corruption**: Check JSON validity in memory.json files
- **PM2 crashes**: Check logs with `pm2 logs {agent} --err`

### Health Checks
Most agents expose `/api/status` or `/api/health` endpoints for monitoring.

## Critical Business Logic

### Digital Samples Agent
Processes DIG-series orders from Shopify, resizes images via Sharp, requires manual approval before sending to customers.

### Legal Team Agent
Monitors product catalog for settlement compliance, checks for tropical design violations.

### Executive Dashboards
CEO, CFO, COO, VP-Ops agents provide high-level business metrics and insights.

### Marketing & Customer Engagement
Marketing agent handles campaigns, Zendesk agent manages customer support, both integrate with Anthropic for AI-powered responses.
- all agents must be running at all times and must fix any issues if the agent restarts more than 20 times. Restart after any rash or system restart. add to claude.md
- all nodes with agents must always have open firewalls