← back to Designer Wallcoverings

DW-Agents/dw-agents/README.md

431 lines

# DW-Agents: Designer Wallcoverings AI Assistant System

**Multi-Agent AI System powered by Claude 4** for automating business operations across Designer Wallcoverings departments.

---

## 🚀 Quick Access

- **Master Control Hub**: http://45.61.58.125:9712
- **Digital Samples Agent**: http://45.61.58.125:9879
- **Legal Team Agent**: http://45.61.58.125:9878

**Login Credentials**:
- Username: `admin`
- Password: `2025`

---

## 📋 System Overview

DW-Agents is a comprehensive AI assistant platform composed of specialized agents, each dedicated to a specific business function:

### Active Agents

#### 1. Master Control Hub (Port 9712)
- **Purpose**: Central dashboard for monitoring and controlling all agents
- **Features**:
  - Real-time agent status monitoring
  - Quick access to all agent dashboards
  - System-wide statistics and health checks
  - Unified control panel for all operations

#### 2. Digital Samples Agent (Port 9879)
- **Purpose**: Automated DIG-series order processing and sample delivery
- **Workflow**:
  1. Monitors Shopify orders via webhooks for DIG-* SKU items
  2. Searches Google Drive for matching sample files
  3. Resizes images to 24" wide @ 150 DPI using Sharp
  4. Posts to Slack #new-products channel for approval
  5. Sends processed files to customers via email
- **Key Features**:
  - Real-time order monitoring
  - Automated image processing
  - Manual approval workflow with dashboard
  - Activity logging and statistics
  - Slack integration for team notifications

#### 3. Legal Team Agent (Port 9878)
- **Purpose**: Settlement agreement compliance monitoring
- **Features**:
  - Automated product catalog scanning
  - Settlement criteria checking (tropical design patterns)
  - Real-time violation alerts
  - Compliance reporting and audit trails

### Planned Agents

#### 4. Purchasing Agent (Port 9880)
- Inventory tracking and stock alerts
- Vendor communication management
- Reorder recommendations
- Support for showroom staff (e.g., Samantha)

#### 5. Marketing Agent (Port 9881)
- Blog post generation from new SKUs
- Social media content creation
- Email campaign drafting (Constant Contact integration)
- SEO-optimized content

#### 6. Accounting Agent (Port 9882)
- Financial reporting and P&L generation
- Expense tracking and categorization
- Invoice management
- Budget forecasting

---

## 🛠️ Technical Architecture

### Tech Stack
- **AI Engine**: Anthropic Claude 4 (via @anthropic-ai/sdk)
- **Backend**: Node.js + Express + TypeScript
- **Process Manager**: PM2 for zero-downtime deployments
- **Image Processing**: Sharp (for DIG sample resizing)
- **Integrations**:
  - Shopify Admin API (orders, products, inventory)
  - Slack Web API (team notifications)
  - Google Drive API (file management)
  - Gmail API (customer emails)
  - Constant Contact API (marketing campaigns)

### Project Structure
```
/root/DW-Agents/
├── master-hub.ts                 # Central control dashboard
├── digital-samples-agent.ts      # DIG-series automation
├── DWLegalTeam/
│   └── legal-agent.ts           # Settlement compliance
├── ecosystem.config.js          # PM2 configuration
├── package.json                 # Dependencies
├── logs/                        # Agent logs
│   ├── hub-*.log
│   ├── digital-samples-*.log
│   └── legal-*.log
└── README.md                    # This file
```

---

## 📦 Installation & Setup

### Prerequisites
- Node.js 20+
- PM2 installed globally: `npm install -g pm2`
- Firewall access to ports 9712, 9878, 9879

### Initial Setup

1. **Install Dependencies**
   ```bash
   cd /root/DW-Agents
   npm install
   ```

2. **Configure Environment Variables**
   - Shopify tokens are pre-configured
   - Slack bot token is set in ecosystem.config.js
   - Anthropic API key in environment

3. **Start All Agents**
   ```bash
   pm2 start ecosystem.config.js
   pm2 save
   ```

4. **Verify Status**
   ```bash
   pm2 list | grep dw-
   ```

---

## 🎮 Usage

### Master Hub Commands

Access the master hub at http://45.61.58.125:9712 to:
- View all agent statuses
- Navigate to individual agent dashboards
- Monitor system-wide statistics
- Manage agent configurations

### Digital Samples Workflow

1. **Automatic Detection**: When a customer orders a DIG-series product on Shopify, the webhook automatically triggers the agent

2. **Processing Pipeline**:
   - Agent receives order data
   - Identifies DIG-* SKU items
   - Searches Google Drive for matching files
   - Resizes images to specification (24" @ 150 DPI)
   - Creates approval entry in dashboard

3. **Manual Approval**:
   - Navigate to http://45.61.58.125:9879
   - Review pending approvals with image previews
   - Click "Approve & Send" to deliver to customer
   - Agent posts to Slack #new-products channel
   - Email sent to customer with processed file

4. **Testing**:
   ```bash
   # Trigger a test DIG order
   curl -X POST http://45.61.58.125:9879/api/test/dig-order \
     -H "Cookie: connect.sid=YOUR_SESSION_COOKIE"
   ```

### Legal Team Monitoring

1. Access http://45.61.58.125:9878
2. Use scan buttons to check products:
   - **Scan Entire Catalog**: Full product review
   - **Scan New Products (24h)**: Recent additions only
   - **Scan SETTLEMENT Tagged**: Pre-flagged items
3. Review violations in activity log
4. Export compliance reports

---

## 🔧 Management & Maintenance

### PM2 Commands

```bash
# View all agents
pm2 list

# View specific agent logs
pm2 logs dw-master-hub
pm2 logs dw-digital-samples
pm2 logs dw-legal-team

# Restart an agent
pm2 restart dw-digital-samples

# Stop all agents
pm2 stop all

# Start all agents
pm2 start ecosystem.config.js

# Monitor in real-time
pm2 monit

# Save current configuration
pm2 save
```

### Log Management

Logs are stored in `/root/DW-Agents/logs/`:
- `hub-out.log` / `hub-error.log` - Master Hub
- `digital-samples-out.log` / `digital-samples-error.log` - Digital Samples
- `legal-out.log` / `legal-error.log` - Legal Team

View recent logs:
```bash
tail -f /root/DW-Agents/logs/digital-samples-out.log
```

### Firewall Configuration

Open ports for new agents:
```bash
sudo ufw allow 9880/tcp  # Purchasing Agent
sudo ufw allow 9881/tcp  # Marketing Agent
sudo ufw allow 9882/tcp  # Accounting Agent
sudo ufw status
```

---

## 🔐 Security

- All agents require authentication (admin/2025)
- Session-based authentication with secure cookies
- Firewall rules restrict access to necessary ports
- Environment variables for sensitive credentials
- HTTPS recommended for production (use reverse proxy)

### Recommended Security Enhancements

1. **Use HTTPS**: Configure nginx or Caddy as reverse proxy
2. **Strong Passwords**: Change default credentials
3. **IP Whitelisting**: Restrict access to trusted IPs
4. **Rate Limiting**: Add rate limits to webhook endpoints
5. **Audit Logging**: Enable comprehensive activity logging

---

## 📊 Monitoring & Statistics

### Key Metrics Tracked

**Digital Samples Agent**:
- Total orders processed
- DIG orders found
- Files processed
- Pending approvals
- Emails sent
- Slack notifications

**Legal Team Agent**:
- Imports monitored
- Violations detected
- Compliant products
- Items needing review

**Master Hub**:
- Agent uptime
- System health
- Response times
- Error rates

### API Endpoints

All agents expose REST APIs for programmatic access:

**Master Hub** (9712):
- `GET /api/agents` - List all agents
- `GET /api/agent/:id/status` - Check agent status
- `GET /api/agents/status` - System-wide status

**Digital Samples** (9879):
- `GET /api/stats` - Agent statistics
- `GET /api/activity` - Activity log
- `POST /api/approve/:id` - Approve sample delivery
- `POST /api/reject/:id` - Reject sample
- `POST /webhook/shopify/orders/create` - Shopify webhook

**Legal Team** (9878):
- `GET /api/stats` - Compliance statistics
- `POST /api/scan/catalog` - Trigger catalog scan
- `POST /api/webhook/import` - Import notification

---

## 🚧 Roadmap & Future Enhancements

### Phase 1 (Completed)
- ✅ Master Control Hub
- ✅ Digital Samples Agent with Shopify + Slack integration
- ✅ Legal Team settlement compliance monitoring
- ✅ PM2 process management
- ✅ Firewall configuration

### Phase 2 (In Progress)
- 🔄 Google Drive integration for Digital Samples
- 🔄 Image resizing with Sharp (24" @ 150 DPI)
- 🔄 Email delivery via Gmail API

### Phase 3 (Planned)
- 📋 Purchasing Agent with Claris integration
- 📋 Marketing Agent with Constant Contact
- 📋 Accounting Agent with QuickBooks
- 📋 Trend Research & Vendor Relations Agent

### Phase 4 (Future)
- Advanced analytics dashboard
- Machine learning for demand forecasting
- Automated vendor ordering
- Multi-language support
- Mobile app interface

---

## 🆘 Troubleshooting

### Agent Won't Start
```bash
# Check logs for errors
pm2 logs dw-digital-samples --err

# Verify dependencies
cd /root/DW-Agents && npm install

# Restart with fresh state
pm2 delete dw-digital-samples
pm2 start ecosystem.config.js
```

### Port Already in Use
```bash
# Find process using port
sudo lsof -i :9712

# Kill process (if needed)
sudo kill -9 <PID>

# Restart agent
pm2 restart dw-master-hub
```

### Webhook Not Receiving Orders
1. Verify Shopify webhook is configured:
   - URL: `http://45.61.58.125:9879/webhook/shopify/orders/create`
   - Event: `Order creation`
   - Format: JSON

2. Check firewall allows Shopify IPs

3. Test webhook manually:
   ```bash
   curl -X POST http://45.61.58.125:9879/webhook/shopify/orders/create \
     -H "Content-Type: application/json" \
     -d '{"order_number": 12345, "line_items": [{"sku": "DIG-12345"}]}'
   ```

### Slack Integration Not Working
1. Verify `SLACK_BOT_TOKEN` in ecosystem.config.js
2. Ensure bot is added to #new-products channel
3. Check bot permissions in Slack app settings

---

## 📞 Support & Contact

For issues, questions, or feature requests:
- System Administrator: stevemdr
- Email: info@designerwallcoverings.com
- Documentation: This README

---

## 📄 License & Credits

**DW-Agents System**
© 2025 Designer Wallcoverings
Powered by Anthropic Claude 4

Built with:
- Node.js & Express
- TypeScript
- Anthropic AI SDK
- Sharp image processing
- Slack Web API
- PM2 process manager

---

## 🎉 Quick Start Checklist

- [x] Install dependencies (`npm install`)
- [x] Configure firewall ports (9712, 9878, 9879)
- [x] Start all agents (`pm2 start ecosystem.config.js`)
- [x] Access Master Hub (http://45.61.58.125:9712)
- [ ] Test Digital Samples workflow with DIG order
- [ ] Configure Shopify webhooks
- [ ] Set up Google Drive credentials
- [ ] Configure Gmail API for email delivery
- [ ] Add Slack bot to #new-products channel
- [ ] Train team on agent usage
- [ ] Set up monitoring alerts
- [ ] Schedule regular backups

---

**System Status**: ✅ **All agents online and operational**

Last Updated: November 5, 2025