mini/docs/CONTENT_GENERATION_SETUP.md

Content Generation System - Complete Setup Guide

🎯 System Overview

The Content Generation Engine is now fully implemented with:

• Spintax Resolution: Handles {A|B|C} syntax
• Variable Expansion: Cartesian products of {{VARIABLES}}
• Uniqueness Tracking: Prevents duplicate variations
• Usage Stats: Tracks block/variation usage
• Full Article Generation: 2000-word articles from templates

📦 Components Built

1. Database Schema (migrations/02_content_generation.sql)

• variation_registry - Track unique combinations
• block_usage_stats - Block usage counts
• spintax_variation_stats - Spintax choice tracking
• Enhanced avatars, campaign_masters, content_fragments

2. Spintax Engine (src/lib/spintax/resolver.ts)

• SpintaxResolver - Resolves {A|B|C} deterministically
• expandVariables() - Replaces {{CITY}} etc
• generateCartesianProduct() - All variable combinations

3. API Endpoints

• POST /api/god/campaigns/create - Submit blueprints
• POST /api/god/campaigns/launch/:id - Queue generation
• GET /api/god/campaigns/status/:id - Check progress

4. BullMQ Worker (src/workers/contentGenerator.ts)

• Fetches campaign blueprints
• Generates Cartesian combinations
• Resolves spintax for each
• Creates posts in DB
• Records all usage stats

5. Admin UI (/admin/content-generator)

• Submit JSON blueprints
• View active campaigns
• Monitor generation stats

🚀 Quick Start

Step 1: Apply Database Schema

# On your server (where DATABASE_URL is set)
psql $DATABASE_URL -f migrations/02_content_generation.sql

Step 2: Start the Worker

# In a separate terminal/process
npm run worker

Step 3: Submit a Campaign

Via UI:

1. Go to https://spark.jumpstartscaling.com/admin/content-generator
2. Click "Load Example"
3. Click "Create Campaign"
4. Launch from campaigns list

Via API:

curl -X POST https://spark.jumpstartscaling.com/api/god/campaigns/create \
  -H "X-God-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Solar Test",
    "blueprint": {
      "asset_name": "{{CITY}} Solar",
      "variables": {
        "CITY": "Miami|Tampa",
        "STATE": "Florida"
      },
      "content": {
        "url_path": "{{CITY}}.solar.com",
        "meta_description": "{Stop|Eliminate} waste in {{CITY}}",
        "body": [
          {
            "block_type": "Hero",
            "content": "<h1>{Title A|Title B} for {{CITY}}</h1>"
          }
        ]
      }
    }
  }'

# Launch it
curl -X POST https://spark.jumpstartscaling.com/api/god/campaigns/launch/CAMPAIGN_ID \
  -H "X-God-Token: YOUR_TOKEN"

📊 How It Works

1. Blueprint Submission

User submits JSON with:

• Variables: "CITY": "A|B|C" creates 3 options
• Spintax: {option1|option2} in content
• Blocks: Array of content sections

2. Cartesian Expansion

CITY: "Miami|Tampa" (2 options)
STATE: "FL|CA" (2 options)
= 4 total combinations

3. Spintax Resolution

For each combination:

• Replace {{CITY}} → "Miami"
• Resolve {Stop|Eliminate} → "Stop" (deterministic)
• Generate hash of choices for uniqueness

4. Post Creation

• Check if variation hash exists
• If unique: Create post in DB
• Record variation + update stats
• Continue to next combination

📈 Usage Tracking

All usage is tracked automatically:

Blocks:

SELECT block_type, total_uses 
FROM block_usage_stats 
ORDER BY total_uses DESC;

Vari ations:

SELECT variation_path, variation_text, use_count
FROM spintax_variation_stats
ORDER BY use_count DESC;

Created Posts:

SELECT COUNT(*) FROM variation_registry WHERE campaign_id = 'YOUR_ID';

🔧 Testing

Test the full system:

npm run test:campaign

This will:

1. Create a test campaign
2. Queue 2 jobs (San Diego, Irvine)
3. Worker processes them
4. Check posts table for results

⚙️ Configuration

Required environment variables:

DATABASE_URL=postgresql://...
REDIS_URL=redis://...
GOD_TOKEN=your_secret_token

🎨 Blueprint Examples

See CONTENT_GENERATION_API.md for full examples and all the JSON blueprints you provided (Solar, Roofing, HVAC, MedSpa, etc.)

✅ Phase 6: Quality Checklist

• Schema created with usage tracking
• Spintax resolver handles nested syntax
• Variables expand correctly
• Cartesian products generate all combinations
• Uniqueness prevents duplicates
• Worker processes jobs asynchronously
• API endpoints secured with GOD_TOKEN
• UI allows blueprint submission
• Usage stats track everything
• Documentation complete
• Build succeeds
• Code pushed to Git

🚢 Deployment

Your code is already pushed to main. To deploy:

1. Apply schema:

   ssh your-server
   cd /path/to/spark
   psql $DATABASE_URL -f god-mode/migrations/02_content_generation.sql
   

2. Start worker: Add to your process manager (PM2, systemd, etc):

   cd god-mode && npm run worker
   

3. Test:

   npm run test:campaign
   

📞 Ready to Use

Your API is ready! Test it:

curl https://spark.jumpstartscaling.com/admin/content-generator

All the JSON blueprints you provided are ready to be submitted and will generate thousands of unique articles with full spintax resolution and usage tracking!