Workflow Model

Tenant registers (provides company website URL)
      │
      ├─► Website crawler starts immediately (agent__tenant-web-crawler)
      │     Playwright BFS crawl — pages, images, documents stored in DB
      │     Homepage analysed for brand signals → colors + fonts written to brand_assets
      │
      ├─► Connect Channels (LinkedIn, Facebook, WordPress, GBP, etc. via OAuth)
      │
      ▼
Onboarding Wizard (/onboarding — 6 steps)
  Step 1: Connect Channels
  Step 2: Brand Voice (tone, personality, writing style)
  Step 3: Brand Assets (colors + fonts — pre-filled from website crawl if found)
  Step 4: Documents (upload brand docs)
  Step 5: Baseline (current traffic, ads, social metrics)
  Step 6: Launch → kicks off setup chain
      │
      ▼
Onboarding Agent (setup chain)
  Researches client: website, competitors, industry, products
  Generates → Client Context File (skill injected into all agents)
      │
      ▼
Strategy Agent
  Reads context file
  Generates → Marketing Strategy (goals + recommended deliverables + rationale)
  Human reviews and approves strategy
      │
      ▼
Goals
  High-level outcomes the strategy aims to achieve
  e.g. "Increase organic website traffic", "Improve local search presence"
  Each goal has a metric and target
      │
      ▼
Deliverables (per goal, recurring monthly)
  Fixed output commitments: 10 blogs, 12 social posts, 10 backlinks, etc.
  Each deliverable has a monthly period tracker
      │
      ▼
Requests (BlogRequest / SocialMediaRequest)
  Raised by an agent (from the deliverable pipeline) OR by a DM team member ad-hoc
  Defines WHAT to create: topic, brief, target audience, target channel(s)
  Goes through approval before any content is created
      │ approved
      ▼
Content Entities (BlogPost / SocialPost)
  Created automatically when the request is approved
  The actual content that agents will write
      │
      ▼
Activities
  Agent writes content → Human reviews → Approved → Published to Channel
  Completing all activities → deliverable unit fulfilled
  Fulfilling all deliverables → goals met

draft → pending_approval → approved → in_progress → completed
                         → rejected → (closed or revised)

created → assigned → in_progress → awaiting_approval → approved → completed
                         │                  │
                         ▼                  ▼
                       failed            rejected → back to in_progress (retry)

Deliverable: 10 Blog Posts — April 2026
Channel: WordPress (acmecorp.com) — connected via OAuth

┌─────────────────────────────────────────────────────────────┐
│ Activity: Research 10 Blog Topics                           │
│ Assigned to: 🤖 SEO Specialist + Content Researcher         │
│ Output: 10 BlogRequests created (status: pending_approval)  │
│         Each has: topic, target keyword, search intent      │
└───────────────────────────┬─────────────────────────────────┘
                            │ completes
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Activity: Review & Approve Blog Requests                    │
│ Assigned to: 👤 Human (DM Portal)                           │
│ Input: 10 BlogRequests                                      │
│ Action: approve all / reject some / edit brief              │
│ On approval of each: BlogPost entity auto-created (draft)   │
└───────────────────────────┬─────────────────────────────────┘
                            │ approved (e.g. 10/10)
                            ▼ (one sub-pipeline per approved BlogPost)
┌─────────────────────────────────────────────────────────────┐
│ Activity: Write Blog Post — "{Topic Title}" [×10]           │
│ Assigned to: 🤖 Copywriter                                   │
│ Input: BlogRequest brief + SEO brief + client context       │
│ Output: BlogPost content updated (status: review)           │
└───────────────────────────┬─────────────────────────────────┘
                            │ completes
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Activity: Review & Approve Blog Post — "{Topic Title}" [×10]│
│ Assigned to: 👤 Human (DM Portal)                           │
│ Action: approve / reject with notes / edit inline           │
│ On approval: BlogPost status → approved                     │
└───────────────────────────┬─────────────────────────────────┘
                            │ approved
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Activity: Publish to WordPress — "{Topic Title}" [×10]      │
│ Assigned to: 🤖 Copywriter (using WordPress channel tokens) │
│ Action: POST to WordPress REST API using stored OAuth token │
│ Output: BlogPost.published_url set; status → published      │
└───────────────────────────┬─────────────────────────────────┘
                            │ published (10/10)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Deliverable COMPLETED: 10 Blog Posts ✅                      │
│ Goal progress updated: Organic Traffic goal +10 blogs       │
└─────────────────────────────────────────────────────────────┘

Deliverable: 10 Backlinks — April 2026
Goal: Improve Domain Authority

Activity: Research 10 Backlink Opportunities
→ 🤖 SEO Specialist (Ahrefs/SEMrush tools)
→ Output: list of 10 target sites with contact details + angle

    Activity: Review Backlink Opportunities
    → 👤 Human approval (filter out irrelevant sites)
    → Output: approved target list

        Activity: Write Outreach Email for each target [×10]
        → 🤖 Copywriter
        → Output: personalised outreach email per site

            Activity: Review Outreach Emails [×10]
            → 👤 Human (DM Portal)
            → Action: approve / edit / reject

                Activity: Send Outreach [×10]
                → 👤 Human (manually send) OR 🤖 via email integration
                → Output: sent confirmation + tracking

Deliverable: 10 Backlinks Outreached ✅

Deliverable: 12 Social Posts — April 2026 (3×/week)
Channels: LinkedIn Company Page + Instagram Business (both connected)
Goal: Brand Awareness + Engagement

┌──────────────────────────────────────────────────────────────┐
│ Activity: Create Social Content Calendar                     │
│ Assigned to: 🤖 Social Media Manager                         │
│ Output: 12 SocialMediaRequests (status: pending_approval)    │
│         Each has: topic, platform(s), format, brief, date    │
└────────────────────────────┬─────────────────────────────────┘
                             │ completes
                             ▼
┌──────────────────────────────────────────────────────────────┐
│ Activity: Review & Approve Content Calendar                  │
│ Assigned to: 👤 Human (DM Portal)                            │
│ Input: 12 SocialMediaRequests                                │
│ Action: approve / edit / reject individual requests          │
│ On approval of each: SocialPost records created              │
│   → 1 SocialPost per channel (LinkedIn + Instagram = 2 each) │
└────────────────────────────┬─────────────────────────────────┘
                             │ approved
                             ▼ (one sub-pipeline per approved SocialPost)
┌──────────────────────────────────────────────────────────────┐
│ Activity: Write Post Content — [×12 requests, ×2 channels]   │
│ Assigned to: 🤖 Copywriter / Social Media Manager            │
│ Input: SocialMediaRequest brief + channel format rules       │
│ Output: Platform-specific copy per SocialPost                │
│   LinkedIn: longer, professional tone (up to 3000 chars)     │
│   Instagram: punchy, hashtags, emoji (up to 2200 chars)      │
└────────────────────────────┬─────────────────────────────────┘
                             │ completes
                             ▼
┌──────────────────────────────────────────────────────────────┐
│ Activity: Review & Approve Posts [×24 SocialPosts]           │
│ Assigned to: 👤 Human (DM Portal)                            │
│ Action: approve / edit / reject per post per platform        │
│ On approval: SocialPost status → approved                    │
└────────────────────────────┬─────────────────────────────────┘
                             │ approved
                             ▼
┌──────────────────────────────────────────────────────────────┐
│ Activity: Publish to Channel — [×24 SocialPosts]             │
│ Assigned to: 🤖 Social Media Manager (using channel tokens)  │
│ LinkedIn: POST /v2/ugcPosts using stored LinkedIn token      │
│ Instagram: POST via Graph API using stored Instagram token   │
│ Output: SocialPost.published_url; status → published         │
└────────────────────────────┬─────────────────────────────────┘
                             │ all 12 requests published
                             ▼
Deliverable COMPLETED: 12 Social Posts ✅
Goal progress updated: Brand Awareness goal

Deliverable: 10 Google Business Profile Posts — April 2026
Channel: Google Business Profile (acmecorp) — connected via GBP OAuth
Goal: Improve Local Search Visibility

Activity: Create 10 GBP Post Requests
→ 🤖 Social Media Manager
→ Output: 10 SocialMediaRequests (type: gbp_post, status: pending_approval)

    Activity: Review GBP Post Requests
    → 👤 Human (DM Portal)
    → On approval: SocialPost records created (channel: GBP)

        Activity: Write each GBP Post [×10]
        → 🤖 Copywriter (short format, local intent, 1500 char limit)
        → Output: SocialPost content updated (status: review)

            Activity: Review GBP Posts [×10]
            → 👤 Human final approval
            → On approval: SocialPost status → approved

                Activity: Publish to GBP [×10]
                → 🤖 Social Media Manager
                → POST via Google Business Profile API using stored OAuth token
                → SocialPost.published_url set; status → published

Deliverable: 10 GBP Posts Published ✅

Lead captured (from any source)
      │
      ▼ (auto-enrichment activity — optional)
🤖 Enrichment: look up company info, LinkedIn profile, etc.
      │
      ▼
Lead visible in CRM (status: new)
      │
      ▼ Human or agent qualifies the lead
      │
      ├── Qualified → lead.status = qualified
      │     │
      │     ▼
      │   (optional) Agent drafts follow-up email
      │   Human reviews + approves → sent via email channel
      │
      └── Disqualified → lead.status = disqualified, reason noted

Channel connected (Google Ads OAuth)
      │
      ▼ (on connect + periodic sync)
┌─────────────────────────────────────────────────────────────┐
│ Activity: Sync Google Ads Campaigns                         │
│ Assigned to: 🤖 Paid Ads Manager                            │
│ Action: Pull campaigns, ad groups, keywords, search terms   │
│ Output: `ad_campaigns`, `ad_groups`, `ad_keywords`,         │
│         `search_term_reports` records upserted in DB        │
└───────────────────────────┬─────────────────────────────────┘
                            │ completes
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Activity: Classify Search Terms                             │
│ Assigned to: 🤖 Paid Ads Manager                            │
│ Input: Raw search terms from sync                           │
│ Output: Each term classified as:                            │
│   - keyword (add as exact/phrase match)                     │
│   - negative_keyword (exclude)                              │
│   - watch (monitor, no action yet)                          │
│ Records: `search_term_classifications` created              │
└───────────────────────────┬─────────────────────────────────┘
                            │ completes
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Activity: Review Search Term Classifications                │
│ Assigned to: 👤 Human (DM Portal / Dashboard)               │
│ Input: classified terms with recommended action             │
│ Action: approve / override classification / skip            │
│ On approval: push to Google Ads API                         │
│   - keyword → add to ad group as exact/phrase match         │
│   - negative → add to campaign negative keyword list        │
└───────────────────────────┴─────────────────────────────────┘

Separately (monthly performance cycle):
┌─────────────────────────────────────────────────────────────┐
│ Activity: Generate Optimization Recommendations             │
│ Assigned to: 🤖 Paid Ads Manager                            │
│ Input: Campaign performance data (CTR, CPC, Conv rate, ROAS)│
│ Output: `ad_optimization_recommendations` records created   │
│   e.g. "Increase bid for X by 15% — reason: CTR 8.2%"      │
└───────────────────────────┬─────────────────────────────────┘
                            │ completes
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Activity: Review & Approve Optimizations                    │
│ Assigned to: 👤 Human (DM Portal / Dashboard)               │
│ Action: approve / reject / snooze per recommendation        │
│ On approval: push changes to Google Ads API                 │
│   (bid adjustments, budget changes, pause/enable keywords)  │
└─────────────────────────────────────────────────────────────┘

Global Recurring Task Templates (managed in Manage App)
      │
      │ On tenant creation: copy global templates → tenant-specific templates
      ▼
Tenant Recurring Task Templates (tenant can customise)
      │
      │ Based on periodicity + trigger: auto-create activities
      ▼
Activities (created on schedule or on trigger)

interface RecurringTaskTemplate {
  id:               string;
  tenantId:         string | null;   // null = global template
  name:             string;          // e.g. "Update Google My Business listing"
  description:      string;
  assigneeType:     'agent' | 'human';
  agentRole?:       AgentRole;
  humanRole?:       'reviewer' | 'admin';
  periodicity:      'one_time' | 'daily' | 'weekly' | 'monthly' | 'quarterly';
  trigger:          'on_onboarding' | 'on_strategy_approval' | 'cron' | 'manual';
  cronExpression?:  string;          // if trigger = 'cron'
  promptTemplate:   string;          // task description with {{variables}} for substitution
  variables:        TemplateVariable[];  // filled in per-tenant (e.g. GBP URL)
  isActive:         boolean;
  sourceTemplateId: string | null;   // global template this was copied from
}
 
interface TemplateVariable {
  key:         string;   // e.g. "gbp_url"
  label:       string;   // e.g. "Google Business Profile URL"
  type:        'string' | 'url' | 'number' | 'select';
  required:    boolean;
  value?:      string;   // filled in at tenant level
}

// Global template prompt:
// "Go to {{gbp_url}} and set the listing to 'Always Open'"
 
// After tenant fills in variables:
// "Go to https://business.google.com/u/0/dashboard/l/ABC123 and set the listing to 'Always Open'"

interface ActivityTemplate {
  deliverableType: DeliverableType;
  steps: ActivityTemplateStep[];
}
 
interface ActivityTemplateStep {
  name:         string;
  assigneeType: 'agent' | 'human';
  agentRole?:   AgentRole;       // if agent
  humanRole?:   'reviewer' | 'approver' | 'admin';  // if human
  inputFrom?:   string;          // step name whose output feeds this step
  isApproval:   boolean;
  repeatPerUnit?: boolean;        // true = one activity per blog post, not one for all
  blockedBy?:   string[];         // step names that must complete first
}

const blogPostTemplate: ActivityTemplate = {
  deliverableType: 'blog_posts',
  steps: [
    {
      name:         'Research topics',
      assigneeType: 'agent',
      agentRole:    'seo-specialist',
      isApproval:   false,
    },
    {
      name:         'Approve topic list',
      assigneeType: 'human',
      humanRole:    'reviewer',
      inputFrom:    'Research topics',
      isApproval:   true,
      blockedBy:    ['Research topics'],
    },
    {
      name:           'Write blog post',
      assigneeType:   'agent',
      agentRole:      'copywriter',
      inputFrom:      'Approve topic list',
      isApproval:     false,
      repeatPerUnit:  true,    // one per approved topic
      blockedBy:      ['Approve topic list'],
    },
    {
      name:           'Review and approve blog post',
      assigneeType:   'human',
      humanRole:      'reviewer',
      inputFrom:      'Write blog post',
      isApproval:     true,
      repeatPerUnit:  true,
      blockedBy:      ['Write blog post'],
    },
  ],
};