Prerequisites

• Node.js 18+ (recommended: v20 LTS)
• npm 9+ or yarn
• Vercel CLI (npm i -g vercel)
• Git

Clone & Install

git clone https://github.com/etoro/cmoclaw-server.git
cd cmoclaw-server
npm install

Environment Variables

# .env
NODE_ENV=development
PORT=3000

# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o

# Salesforce Marketing Cloud
SFMC_INSTANCE_URL=https://mcXXXXXX.rest.marketingcloudapis.com
SFMC_CLIENT_ID=...
SFMC_CLIENT_SECRET=...
SFMC_ACCOUNT_ID=...

# Databricks
DATABRICKS_HOST=https://xxx.cloud.databricks.com
DATABRICKS_TOKEN=dapi...
DATABRICKS_WAREHOUSE_ID=...

# Meta Marketing API
META_APP_ID=...
META_APP_SECRET=...
META_ACCESS_TOKEN=...
META_AD_ACCOUNT_ID=act_...

# Google Ads
GOOGLE_ADS_DEVELOPER_TOKEN=...
GOOGLE_ADS_CLIENT_ID=...
GOOGLE_ADS_CLIENT_SECRET=...
GOOGLE_ADS_REFRESH_TOKEN=...
GOOGLE_ADS_CUSTOMER_ID=...

# TikTok
TIKTOK_APP_ID=...
TIKTOK_SECRET=...
TIKTOK_ACCESS_TOKEN=...
TIKTOK_ADVERTISER_ID=...

# ChromaDB
CHROMA_HOST=localhost
CHROMA_PORT=8000

Running Locally

# Development mode with hot reload
npm run start:dev

# Production build
npm run build
npm run start:prod

# Run tests
npm test

Module Structure (18 Modules)

src/
├── app.module.ts              # Root module
├── auth/                      # Authentication & guards
├── campaign/                  # Campaign CRUD & lifecycle
├── content/                   # AI content generation
├── segmentation/              # CHAID trees & clustering
├── channels/
│   ├── meta/                  # Meta/Facebook Ads
│   ├── google/                # Google Ads
│   ├── tiktok/                # TikTok Ads
│   ├── taboola/               # Taboola
│   ├── dv360/                 # Display & Video 360
│   ├── bing/                  # Bing Ads
│   └── x/                     # X/Twitter Ads
├── email/                     # MJML templates & sending
├── compliance/                # Regulatory AI checks
├── analytics/                 # Performance tracking
├── rag/                       # Vector DB & campaign memory
├── workflow/                  # n8n integration
└── common/                    # Shared utilities, DTOs, guards

Database Schema

Users         → id, email, segment_id, behavior_data, created_at
Segments      → id, name, chaid_tree, criteria, user_count
Campaigns     → id, name, status, channels[], content_id, segment_id
Creatives     → id, campaign_id, type, content, channel, variants[]
Performance   → id, campaign_id, channel, impressions, clicks, conversions
AuditLog      → id, action, user_id, campaign_id, timestamp, details

Authentication Flow

JWT-based authentication with refresh tokens. API keys for service-to-service communication. Rate limiting per API key (100 req/min default).

POST /api/auth/login    → { access_token, refresh_token }
POST /api/auth/refresh  → { access_token }
GET  /api/auth/me       → { user profile }

Vercel (Frontend)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

AWS (Backend — EC2/ECS)

# Build Docker image
docker build -t cmoclaw-server .

# Push to ECR
aws ecr get-login-password | docker login --username AWS --password-stdin ACCOUNT.dkr.ecr.REGION.amazonaws.com
docker tag cmoclaw-server:latest ACCOUNT.dkr.ecr.REGION.amazonaws.com/cmoclaw-server:latest
docker push ACCOUNT.dkr.ecr.REGION.amazonaws.com/cmoclaw-server:latest

# Deploy to ECS
aws ecs update-service --cluster cmoclaw --service cmoclaw-server --force-new-deployment

CI/CD Pipeline

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: vercel --prod --token ${{ secrets.VERCEL_TOKEN }}

Channel API Setup

Each channel requires OAuth2 credentials. See the Gap Analysis for what's needed per channel.

Salesforce Marketing Cloud

// src/channels/sfmc/sfmc.service.ts
// Requires: Server-to-Server API integration package
// Auth: OAuth2 client credentials flow
// Endpoints: REST API for data extensions, SOAP API for sends

Databricks Connection

// Uses Databricks SQL connector
// Connection via personal access token
// SQL warehouse for query execution
// Unity Catalog for data governance

n8n Workflow Setup

# Install n8n locally
npm install -g n8n

# Start n8n
n8n start

# Import workflows from /workflows directory
# Configure webhook URLs in .env

OpenAI Configuration

// Default model: gpt-4o
// Fallback: gpt-4o-mini (for compliance checks)
// Temperature: 0.7 (content), 0.1 (compliance)
// Max tokens: 2000 (content), 500 (compliance)

Monitoring & Logging

Structured JSON logging via NestJS Logger. Ready for DataDog/New Relic integration. Key metrics: request latency, AI generation time, channel API response times, error rates.

Error Handling

// Global exception filter catches all errors
// Channel-specific retry logic (3 retries, exponential backoff)
// Dead letter queue for failed campaign sends
// Alert on >5% error rate per channel

Rate Limiting

// Per-client: 100 requests/minute
// AI generation: 10 requests/minute (OpenAI limits)
// Channel APIs: Varies (Meta: 200/hr, Google: 15000/day)
// Configurable via environment variables

Feature Flags

// Feature flags via environment variables
FEATURE_RAG_ENABLED=true
FEATURE_ML_PREDICTIONS=false
FEATURE_REALTIME_OPTIMIZATION=false
FEATURE_MULTI_CHANNEL=true