Hugging Face's logo

AmitGurawa
/
influencer-platform-technical-design

Model card Files
xet
 Community

YAML Metadata Warning:empty or missing yaml metadata in repo card

Check out the documentation for more information.

Technical Design Document — v2.0

AI-Powered Influencer Campaign Automation Platform

Version: 2.0 (Revised — incorporates Grok market research, Claude architecture review, and open-source tooling audit)
Date: April 30, 2026
Author: Technical Architecture Team
Status: PROPOSAL — Pre-Scoping Phase

📋 View v1.0 (archived) | This is the current version.

Changelog from v1.0

Area v1.0 v2.0 Change Rationale
Orchestration Custom cron on Railway n8n (self-hosted) as orchestration engine Eliminates ~2 weeks of custom scheduling/retry code; 400+ native integrations; visual workflow debugging
Sentiment GPT-4o-mini only Tiered: XLM-RoBERTa (bulk) → GPT-4o-mini (edge cases) 10× cheaper at scale; open-source multilingual model handles 90% of comments; LLM for ambiguous/Hinglish/sarcasm
FAQ Handling Direct LLM pgvector RAG inside Supabase Zero extra infra (pgvector built into Supabase); semantic FAQ search; avoids hallucinated answers
Voice Fallback Pre-recorded + live transfer AI Voice Agent: Twilio Voice + Deepgram STT + ElevenLabs TTS Market research shows indie builders achieving this; competitive differentiator
Dashboard (v1 fast-track) Next.js + Tremor custom build Metabase (OSS, v1) → Next.js + Tremor (v2) Ship dashboard in 2 days not 2 weeks; Metabase connects directly to PostgreSQL; upgrade to custom UI later
Budget Guardrails In LLM prompt Hard-coded rule engine OUTSIDE LLM Claude research flagged prompt injection risk; guardrail layer never passes max budget to agent context
WhatsApp Channel Only Cloud API Cloud API (primary) + Evolution API/WAHA as dev/test sandbox Open-source WhatsApp HTTP APIs for local development without burning Meta API quota
Conversation Logging Custom implementation Chatwoot (OSS) as conversation inbox layer 21K+ GitHub stars; built-in WhatsApp integration, agent assignment, conversation history UI
Out of Scope → In Scope Multi-language (English only) Hinglish/Hindi support via multilingual models + LLM Grok research: "If targeting India-heavy creators, factor local WhatsApp adoption and regional API nuances"
New Section N/A §15 — Open-Source Tooling Map with GitHub repos, stars, and "build vs reuse" recommendation Direct request; avoids reinventing the wheel
New Section N/A §16 — Competitive Landscape & Market Intel Synthesized from Grok research; informs positioning and pricing

Table of Contents

  1. Executive Summary
  2. Problem Statement
  3. Architecture Overview
  4. Module 1 — Outreach & Negotiation Agent
  5. Module 2 — Instagram Engagement Dashboard
  6. Module 3 — Influencer Discovery Engine
  7. Data Architecture
  8. Infrastructure & DevOps
  9. Security & Compliance
  10. Cost Estimation
  11. Risk Register & Mitigations
  12. Development Timeline
  13. Team Structure
  14. Assumptions, Dependencies & Out of Scope
  15. Open-Source Tooling Map — Build vs. Reuse
  16. Competitive Landscape & Market Intel
  17. Appendix — Tech Lead Review
  18. Appendix — API Rate Limits
  19. Appendix — Glossary
  20. Next Steps

1. Executive Summary

This document defines the architecture for an end-to-end influencer campaign automation platform with three modules:

Module Function Core Stack
M1 — Outreach Agent Google Sheets → WhatsApp/Voice → AI negotiation → human handoff → deal close WhatsApp Cloud API + LangGraph + GPT-4o + n8n
M2 — IG Dashboard Post detection → engagement tracking → sentiment analysis → anomaly alerts → ROI Instagram Graph API + Phyllo + Supabase + Metabase (v1) / Next.js (v2)
M3 — Discovery Auto-discover influencers → deduplicate → enrich → add to pipeline Modash API + n8n cron

Key architectural philosophy: Use open-source where it saves >1 week of dev time; build custom only where differentiation matters (the negotiation agent FSM).

The platform maximizes open-source tooling to avoid reinventing the wheel:

  • n8n (52K+ ⭐) for workflow orchestration instead of custom schedulers
  • Chatwoot (21K+ ⭐) for conversation inbox instead of custom chat UI
  • Metabase (40K+ ⭐) for v1 dashboard instead of custom charts
  • Evolution API (2K+ ⭐) or WAHA for WhatsApp dev/test sandbox
  • cardiffnlp/twitter-xlm-roberta-base-sentiment-multilingual for bulk sentiment (free, multilingual)
  • pgvector (Supabase-native) for FAQ retrieval instead of Pinecone

Custom code is concentrated in the LangGraph negotiation state machine — the core IP of the platform.

2. Problem Statement

2.1 Current State

  • Campaign managers maintain influencer lists in Google Sheets
  • Each influencer contacted individually via phone/WhatsApp
  • Pitching, FAQ handling, rate negotiation done person-to-person
  • Zero post-campaign visibility into engagement, ROI, or influencer performance
  • New influencer sourcing is ad hoc with no systematic discovery

2.2 Target State

  • Automated outreach triggered from Google Sheets data
  • AI agent handles pitch → FAQ → negotiation → close/escalate
  • Humans only intervene for hot leads flagged by the agent
  • Real-time IG engagement data per influencer and per campaign
  • Systematic creator discovery refreshing the pipeline every 2-3 days

2.3 Market Context (from Grok Research)

What the market says about this category:

  • Sentiment: "Cautiously optimistic with growing adoption" — brands see value in automating "80% of grunt work"
  • Key pain point: Generic templates lead to low response rates; influencers spot templated pitches
  • Critical success factor: Hyper-personalization referencing specific posts/content, not just "Hi {name}"
  • Competitive edge of our approach: Most existing tools (Grin, AspireIQ, Modash) are discovery + tracking platforms, NOT automated negotiation agents. Janney AI is the closest competitor but doesn't support WhatsApp as primary channel
  • India-specific: WhatsApp is dominant; Hinglish (Hindi+English mix) is common in influencer conversations; regional language support is a differentiator

3. Architecture Overview 

┌────────────────────────────────────────────────────────────────────────────┐
│                         CLIENT INTERFACE LAYER                             │
│                                                                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Google Sheets │  │    Slack     │  │  Metabase    │  │  Chatwoot    │  │
│  │ (Influencer  │  │  (Human     │  │  Dashboard   │  │  (Conv.      │  │
│  │  Master List)│  │   Handoff)  │  │  (IG metrics)│  │   Inbox)     │  │
│  └──────┬───────┘  └──────▲──────┘  └──────▲───────┘  └──────▲───────┘  │
└─────────┼─────────────────┼────────────────┼──────────────────┼──────────┘
          │                 │                │                  │
┌─────────┼─────────────────┼────────────────┼──────────────────┼──────────┐
│         ▼                 │                │                  │          │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                    n8n ORCHESTRATION ENGINE                         │ │
│  │  (self-hosted, 52K+ ⭐)                                            │ │
│  │                                                                     │ │
│  │  Workflows:                                                         │ │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────────┐  │ │
│  │  │ Sheet Sync      │  │ Outreach        │  │ IG Polling         │  │ │
│  │  │ (every 60s or   │  │ Trigger         │  │ (every 4h metrics  │  │ │
│  │  │  webhook)       │  │ (new rows →     │  │  every 2h posts)   │  │ │
│  │  │                 │  │  queue → agent)  │  │                    │  │ │
│  │  └─────────────────┘  └─────────────────┘  └────────────────────┘  │ │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────────┐  │ │
│  │  │ Discovery       │  │ Sentiment       │  │ Anomaly Detection  │  │ │
│  │  │ (every 3 days)  │  │ Batch           │  │ (daily 2 AM)       │  │ │
│  │  │                 │  │ (every 4h)      │  │                    │  │ │
│  │  └─────────────────┘  └─────────────────┘  └────────────────────┘  │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
│  ┌───────────────────────┐  ┌────────────────────────────────────────┐   │
│  │  AI AGENT SERVICE     │  │  DATA SERVICES                        │   │
│  │  (Python / FastAPI)   │  │                                        │   │
│  │                       │  │  ┌────────────────────────────────┐    │   │
│  │  ┌─────────────────┐  │  │  │ Supabase                       │    │   │
│  │  │ LangGraph FSM   │  │  │  │ (PostgreSQL + pgvector +       │    │   │
│  │  │ (negotiation    │  │  │  │  Realtime + Auth + RLS)        │    │   │
│  │  │  state machine) │  │  │  └────────────────────────────────┘    │   │
│  │  ├─────────────────┤  │  │  ┌────────────────────────────────┐    │   │
│  │  │ Budget          │  │  │  │ Redis                           │    │   │
│  │  │ Guardrail Layer │  │  │  │ (message queue, session cache)  │    │   │
│  │  │ (hard-coded,    │  │  │  └────────────────────────────────┘    │   │
│  │  │  outside LLM)   │  │  │                                        │   │
│  │  └─────────────────┘  │  └────────────────────────────────────────┘   │
│  └───────────────────────┘                                               │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐    │
│  │  EXTERNAL APIs                                                   │    │
│  │                                                                   │    │
│  │  WhatsApp Cloud API (Meta) ←── primary messaging channel          │    │
│  │  Twilio Voice + Deepgram + ElevenLabs ←── voice fallback         │    │
│  │  OpenAI GPT-4o / GPT-4o-mini ←── LLM backbone                   │    │
│  │  Instagram Graph API ←── engagement data (free, permissioned)     │    │
│  │  Phyllo API ←── engagement fallback (paid, no permissions needed) │    │
│  │  Modash API ←── influencer discovery                              │    │
│  │  Slack API ←── human handoff notifications                        │    │
│  │  HuggingFace Inference API ←── XLM-RoBERTa sentiment (free tier) │    │
│  └──────────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────────┘

Hosting: n8n + AI Agent Service on Railway (or Render) | Supabase (managed) | Metabase on Railway (Docker) | Vercel (if/when custom Next.js dashboard in v2)

4. Module 1 — Outreach & Negotiation Agent

4.1 Messaging Channel: WhatsApp Cloud API (Direct)

Decision unchanged from v1: WhatsApp Cloud API (Meta-hosted) — NOT Twilio-mediated.

Factor WhatsApp Cloud API (Direct) Twilio WhatsApp WATI 360dialog
Cost Meta per-convo fee only (~$0.03-0.08) Meta fee + $0.005/msg $49-99/mo + Meta $49-299/mo + Meta (zero markup)
Template Control Direct via Meta BM Via Twilio console Via WATI dashboard Via 360dialog
Dev Complexity Moderate Lower Lowest (no-code) Moderate
Best For Custom AI agents (our case) Multi-channel enterprises SMBs wanting ease High-volume broadcasts

Why Cloud API still wins: We need raw webhook control for our LangGraph agent. WATI/360dialog abstract too much. Twilio adds unnecessary cost and latency.

NEW in v2 — Dev/Test Sandbox: Use Evolution API (open-source, 2K+ ⭐) or WAHA for local development. These self-hosted WhatsApp HTTP APIs let engineers test message flows without burning Meta API quota or waiting for template approvals.

Critical constraints (unchanged):

  1. 24-hour conversation window rule
  2. Template categories: marketing (outreach) = most expensive
  3. Quality rating system — pace at 50 new outreach/hr max
  4. Business verification required Day 1 (1-2 weeks lead time)

4.2 Voice Fallback: AI Voice Agent (Upgraded from v1)

v1: Pre-recorded pitch + live transfer.
v2: Full AI voice agent using Twilio Voice + Deepgram STT + ElevenLabs TTS.

Influencer picks up phone
        │
        ▼
┌─────────────────────────┐
│ Twilio Voice streams     │
│ audio to Deepgram STT    │──→ Text transcription
└─────────────────────────┘         │
                                    ▼
                            ┌──────────────┐
                            │ LangGraph    │──→ Response text
                            │ Agent        │
                            │ (same FSM as │
                            │  WhatsApp)   │
                            └──────────────┘
                                    │
                                    ▼
                            ┌──────────────┐
                            │ ElevenLabs   │──→ Audio stream
                            │ TTS          │     back to Twilio
                            └──────────────┘

Why upgrade: Grok research shows indie builders achieving this stack. It's a differentiator vs. Janney AI (email-only outreach). Same LangGraph FSM handles both WhatsApp text and voice — one codebase, two channels.

Guardrail: If voice agent detects confusion or negative sentiment for >2 turns → warm transfer to human. Agent says: "Let me connect you with our team directly."

4.3 AI Negotiation Agent: LangGraph State Machine

Architecture unchanged from v1 but with two critical additions from Claude research:

Addition 1: Budget Guardrail Layer OUTSIDE the LLM

# Guardrail layer — runs BEFORE LLM response is sent
class BudgetGuardrail:
    """Hard-coded rules. LLM never sees max budget."""
    
    def validate_offer(self, agent_response, campaign_config):
        proposed_rate = extract_rate(agent_response)
        
        if proposed_rate is None:
            return agent_response  # Not a rate offer, pass through
        
        if proposed_rate > campaign_config.budget_max:
            # BLOCK — never send this. Escalate instead.
            return ESCALATE_TO_HUMAN
        
        if proposed_rate < campaign_config.budget_min:
            # Agent tried to undercut — fix to min
            return replace_rate(agent_response, campaign_config.budget_min)
        
        return agent_response  # Within band, safe to send

Why this matters: Claude research flagged prompt injection risk — a sophisticated influencer could theoretically manipulate the LLM into revealing budget ceilings or agreeing above max. The guardrail layer makes this impossible because the max budget value never enters the LLM context.

Addition 2: FAQ Knowledge Base via pgvector RAG

┌────────────────────────────┐
│ Campaign Setup              │
│ Admin uploads FAQ doc       │
│ → Chunked + embedded        │
│ → Stored in Supabase        │
│   pgvector table            │
└────────────┬───────────────┘
             │
┌────────────▼───────────────┐
│ Influencer asks question    │
│ → Embedded via OpenAI       │
│ → Similarity search pgvector│
│ → Top 3 chunks as context   │
│ → GPT-4o-mini generates     │
│   answer from chunks ONLY   │
│ → If confidence < 0.7:      │
│   "Let me check on that"    │
│   → queued for human        │
└────────────────────────────┘

Why pgvector over Pinecone: Supabase has native pgvector support. Zero extra infrastructure, zero extra cost, zero extra vendor. FAQ corpus for a campaign is tiny (~50-200 chunks) — pgvector handles this trivially.

4.4 Conversation Inbox: Chatwoot (Open-Source)

NEW in v2. Instead of building a custom conversation log viewer, we use Chatwoot (21K+ ⭐):

What Chatwoot gives us for free What we'd have to build otherwise
Multi-channel inbox (WhatsApp, email, web) Custom chat UI
Agent assignment + conversation routing Custom routing logic
Conversation history with search Custom transcript viewer
Canned responses + macros N/A
Contact management Basic influencer CRM
API for programmatic message sending Custom API layer
WhatsApp Business API integration Custom webhook handling
Team collaboration features N/A

Integration pattern:

  1. WhatsApp webhooks → Chatwoot (handles message display + history)
  2. Chatwoot webhook → our LangGraph agent (handles AI response generation)
  3. LangGraph response → Chatwoot API (sends response back through WhatsApp)
  4. Human handoff: agent marks conversation in Chatwoot, human picks up in same inbox

Trade-off: Adds a dependency (Chatwoot self-hosted). But saves ~3 weeks of custom UI development and gives the operations team a professional inbox from Day 1.

4.5 Google Sheets Integration

Unchanged from v1 — bidirectional sync via Sheets API v4. n8n has a native Google Sheets node that handles this with zero custom code.

4.6 Human Handoff Flow

Unchanged from v1 — Slack notification with interactive buttons. n8n handles the Slack notification trigger.

4.7 LLM Selection

Revised based on both research reports:

Role Model Cost Rationale
Negotiation turns GPT-4o $2.50/$10.00 per 1M tokens Best structured output + multilingual (Hinglish)
FAQ from RAG chunks GPT-4o-mini $0.15/$0.60 per 1M tokens 70% cheaper; FAQ is straightforward Q&A
Bulk sentiment (English) XLM-RoBERTa (self-hosted or HF Inference) FREE Open-source, handles 90% of comments
Sentiment edge cases GPT-4o-mini $0.15/$0.60 per 1M tokens Hinglish sarcasm, emoji-heavy, ambiguous
Voice STT Deepgram Nova-2 $0.0043/min Fastest, most accurate for conversational audio
Voice TTS ElevenLabs $0.18/1K chars (Pro) Most natural-sounding for Indian English

5. Module 2 — Instagram Engagement Dashboard

5.1 Data Collection: Dual-Layer (Unchanged)

Graph API (primary, free) + Phyllo (fallback, paid). See v1 for decision logic.

5.2 Sentiment Analysis: Tiered Approach (NEW in v2)

Claude research recommended cardiffnlp/twitter-roberta-base-sentiment. We adopt a tiered version:

                    ┌─────────────────────┐
                    │ Instagram Comments   │
                    │ (batch every 4h)     │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
            ┌───── │ Language Detection   │ ─────┐
            │      └──────────────────────┘      │
            │                                     │
     English/European                    Hindi/Hinglish/
     languages                           Regional/Emoji-heavy
            │                                     │
            ▼                                     ▼
┌──────────────────────┐            ┌───────────────────────┐
│ TIER 1: XLM-RoBERTa  │            │ TIER 2: GPT-4o-mini   │
│ (HF Inference API     │            │ (with structured       │
│  or self-hosted)      │            │  output JSON mode)     │
│                       │            │                        │
│ cardiffnlp/twitter-   │            │ Handles:               │
│ xlm-roberta-base-     │            │ - Code-mixed text      │
│ sentiment-multilingual│            │ - Sarcasm              │
│                       │            │ - Heavy emoji usage    │
│ 10.8M downloads       │            │ - Slang/abbreviations  │
│ Multilingual trained   │            │                        │
│ FREE on HF Inference  │            │ ~$0.15/1M tokens       │
│ ~50ms per comment     │            │ ~500ms per comment     │
│                       │            │                        │
│ Output: pos/neg/neu   │            │ Output: pos/neg/neu/   │
│ + confidence score    │            │ spam + topics +        │
│                       │            │ purchase_intent        │
└──────────┬────────────┘            └──────────┬────────────┘
           │                                     │
           │    ┌─────────────────────┐          │
           └───→│ IF confidence < 0.6 │──────────┘
                │ → route to Tier 2   │  (fallback)
                └─────────────────────┘
                           │
                           ▼
                ┌─────────────────────┐
                │ Store in Supabase   │
                │ [comments] table    │
                └─────────────────────┘

Why tiered:

  • XLM-RoBERTa handles ~80-90% of comments (English, Spanish, Portuguese, French, etc.) at zero marginal cost
  • Only truly ambiguous comments (low confidence) or code-mixed Hinglish route to GPT-4o-mini
  • At 10K comments/campaign: ~9K free (Tier 1) + ~1K at $0.15/1M tokens (Tier 2) = ~$0.002 total. vs. $1.50 if all via GPT-4o-mini

5.3 Dashboard: Metabase (v1) → Next.js + Tremor (v2)

NEW in v2. Instead of building a custom dashboard from Day 1:

Phase 1 (v1): Metabase (open-source, 40K+ ⭐)

  • Docker deploy on Railway (~5 min setup)
  • Connect directly to Supabase PostgreSQL
  • Built-in: chart builder, dashboard creator, filters, drill-downs, scheduled reports, embedding
  • The ops team can build their own views without engineering help
  • Time to ship: 2 days (vs. 2 weeks for custom)

Phase 2 (v2, Week 12+): Custom Next.js + Tremor

  • Only if/when Metabase's limitations become clear (specific UX needs, real-time, custom anomaly views)
  • By then, we know exactly what views the client uses most → build those specifically

5.4 Anomaly Detection

Unchanged from v1 — Modified Z-Score with rolling baseline. Integrated as an n8n workflow running daily at 2 AM.

5.5 Polling Architecture

Unchanged from v1 but now managed by n8n workflows instead of custom cron:

n8n Workflow Schedule Action
poll_new_posts Every 2 hours Detect campaign posts (hashtag + mention + content match)
poll_ig_metrics Every 4 hours Pull engagement snapshots for tracked posts
deep_pull_metrics Daily 2 AM Full historical pull + anomaly detection + engagement rate recalc
sentiment_batch Every 4 hours Batch comments → tiered sentiment analysis

6. Module 3 — Influencer Discovery Engine

Unchanged from v1. Modash API, every 3 days, deduplicate on IG handle. Now orchestrated by n8n workflow.

7. Data Architecture

7.1 Database Schema

Unchanged from v1 (campaigns, influencers, conversations, campaign_posts, engagement_snapshots, comments, anomalies) with one addition:

-- NEW: FAQ knowledge base for RAG
CREATE TABLE faq_chunks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    campaign_id UUID REFERENCES campaigns(id),
    content TEXT NOT NULL,
    embedding VECTOR(1536),  -- OpenAI text-embedding-3-small
    source_document TEXT,
    chunk_index INTEGER,
    created_at TIMESTAMPTZ DEFAULT now()
);

-- pgvector index for similarity search
CREATE INDEX ON faq_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 10);

7.2 Message Bus: Redis

NEW in v2 (from Claude architecture). Redis Pub/Sub for decoupling:

  • n8n publishes outreach trigger → Redis → Agent service consumes
  • Agent publishes state change → Redis → n8n consumes → updates Sheet + Slack
  • Prevents tight coupling between orchestration and agent service

8. Infrastructure & DevOps

8.1 Revised Tech Stack

Layer Technology Open-Source? Justification
Orchestration n8n (self-hosted) ✅ 52K+ ⭐ Replaces custom cron/schedulers; visual workflow builder; native Google Sheets, Slack, WhatsApp nodes
AI Agent Python FastAPI + LangGraph ✅ LangGraph OSS Core IP — custom state machine for negotiation
LLM OpenAI GPT-4o / GPT-4o-mini ❌ (API) Best structured output + multilingual
Conversation Inbox Chatwoot (self-hosted) ✅ 21K+ ⭐ Professional inbox for ops team; WhatsApp native
Database Supabase (PostgreSQL + pgvector + Realtime) ✅ (managed OSS) Unified: relational + vector + realtime + auth
Message Queue Redis ✅ Decouple orchestration ↔ agent
Dashboard (v1) Metabase (self-hosted) ✅ 40K+ ⭐ Ship in 2 days; connects to PostgreSQL directly
Dashboard (v2) Next.js + Tremor + Tailwind ✅ Custom UX when Metabase limits are reached
Sentiment (bulk) XLM-RoBERTa via HF Inference ✅ Free, multilingual, 10.8M downloads
WhatsApp WhatsApp Cloud API (Meta) ❌ (API) Production messaging channel
WhatsApp (dev/test) Evolution API or WAHA ✅ 2K+ ⭐ Local testing without Meta API quota
Voice Twilio + Deepgram + ElevenLabs ❌ (APIs) AI voice agent pipeline
IG Data Instagram Graph API + Phyllo ❌ (APIs) Free primary + paid fallback
Discovery Modash API ❌ (API) Best DB + API for the price
Monitoring Sentry + Posthog ✅ (free tiers) Errors + product analytics
CI/CD GitHub Actions ✅ Standard
Hosting Railway (all backend services) ❌ (PaaS) Simple Docker deploys; cheaper than AWS at this scale

8.2 Service Map on Railway 

Railway Project
├── Service: n8n (Docker)           — 1 GB RAM — $10/mo
├── Service: agent-service (Python) — 512 MB RAM — $5/mo
├── Service: chatwoot (Docker)      — 2 GB RAM — $15/mo
├── Service: metabase (Docker)      — 1 GB RAM — $10/mo
├── Service: redis                  — 256 MB RAM — $3/mo
└── Total Railway: ~$43/mo

External Managed:
├── Supabase Pro: $25/mo
└── Domain + DNS: $15/mo

9. Security & Compliance

Unchanged from v1 with one addition:

9.4 Prompt Injection Prevention (NEW)

WhatsApp messages from influencers are untrusted input flowing into an LLM:

  • Input sanitization: Strip any system-prompt-like patterns ("ignore previous instructions", "you are now", etc.)
  • Budget isolation: Max budget value NEVER enters LLM context. Guardrail layer validates outputs.
  • Output validation: Every agent response checked for: PII leakage, profanity, off-brand content, rates outside band
  • Conversation length limit: Max 15 turns before auto-escalate to human (prevents adversarial probing)

10. Cost Estimation

10.1 Monthly Cost — 100 Influencers

Item v1 Cost v2 Cost Savings Notes
WhatsApp Cloud API $15 $15 — Unchanged
OpenAI GPT-4o (negotiation) $5 $5 — Unchanged
OpenAI GPT-4o-mini (FAQ + sentiment edge) $0.30 $0.30 — Reduced role — only edge cases
XLM-RoBERTa sentiment N/A $0 $0.30 saved HF Inference free tier or self-hosted
Phyllo API $90 $90 — Unchanged
Modash API $120 $120 — Unchanged
Supabase Pro $25 $25 — Now includes pgvector (no Pinecone needed)
Vercel $20 $0 $20 saved No custom frontend in v1; Metabase instead
Railway (all services) $15 $43 +$28 More services (n8n, Chatwoot, Metabase, Redis)
Slack $0 $0 — Free tier
Twilio Voice $1 $8 +$7 AI voice agent uses more minutes
Deepgram STT N/A $3 +$3 ~700 min at $0.0043/min
ElevenLabs TTS N/A $5 +$5 Pro plan allocation
Sentry + Posthog $0 $0 — Free tiers
Domain $15 $15 — Unchanged
TOTAL ~$306 ~$329 +$23 +8% cost for significantly more capability

10.2 Monthly Cost — 500 Influencers

Item Monthly Cost
WhatsApp Cloud API ~$75
OpenAI (all models) ~$25
XLM-RoBERTa $0
Phyllo API ~$450
Modash API $299
Supabase $25
Railway $60
Twilio + Deepgram + ElevenLabs ~$30
TOTAL ~$964

Key insight unchanged: Phyllo is the biggest cost driver. Push Graph API OAuth adoption aggressively.

11. Risk Register & Mitigations

All 10 risks from v1 unchanged, plus:

# Risk Probability Impact Mitigation
R11 Prompt injection via WhatsApp messages Low High Input sanitization + budget isolation + output validation (see §9.4)
R12 n8n single point of failure Low High n8n persists workflows to PostgreSQL; auto-restart on Railway; daily backup
R13 Chatwoot self-hosted maintenance burden Medium Low Use Chatwoot Docker image with auto-updates; community edition is stable (21K+ ⭐)
R14 Influencers detect AI and refuse to engage Medium Medium Transparent disclosure + hyper-personalization (reference specific recent posts, not just "Hi {name}"); immediate human handoff option
R15 Competitor (Janney AI) launches WhatsApp feature Low Medium Speed to market; our WhatsApp + voice combo is harder to replicate; focus on India market

12. Development Timeline

Revised Timeline (incorporates open-source tooling — net schedule unchanged at 10 weeks but with more capability delivered) 

PHASE 0 — Foundation (Week 1-2)
├── Week 1
│   ├── Day 1-2: Infrastructure setup
│   │   ├── Railway: deploy n8n, Redis, Chatwoot (Docker)
│   │   ├── Supabase: project + full schema migration (incl. pgvector)
│   │   ├── GitHub repo (monorepo: services/agent, services/monitor)
│   │   ├── CI/CD: GitHub Actions → Railway
│   │   └── ⚠️ START Meta Business Verification
│   │
│   ├── Day 3-4: Google Sheets + Slack
│   │   ├── n8n: Google Sheets sync workflow (bidirectional)
│   │   ├── n8n: Slack notification workflow (templated alerts)
│   │   └── Test: add row in Sheet → appears in Supabase → Slack ping
│   │
│   └── Day 5: WhatsApp Cloud API
│       ├── Meta Business Manager app setup
│       ├── Webhook endpoint (FastAPI)
│       ├── Template messages submitted for approval
│       ├── Evolution API / WAHA sandbox for dev testing
│       └── Chatwoot ↔ WhatsApp connection configured
│
├── Week 2
│   ├── Day 6-7: Auth + Chatwoot config
│   │   ├── Supabase Auth (Google OAuth)
│   │   ├── Chatwoot: team setup, canned responses, WhatsApp channel
│   │   └── Chatwoot webhook → FastAPI agent endpoint
│   │
│   ├── Day 8-9: Metabase dashboard (v1)
│   │   ├── Deploy Metabase Docker on Railway
│   │   ├── Connect to Supabase PostgreSQL
│   │   ├── Build: campaign overview, influencer table, engagement charts
│   │   └── Build: anomaly log view, conversation status board
│   │
│   └── Day 10: Integration testing
│       ├── Sheet → Supabase → WhatsApp → Chatwoot flow
│       ├── Slack notification delivery
│       └── Metabase reads from live Supabase data
│
│   ✅ DELIVERABLE: Full infra live. WhatsApp send/receive working.
│      Chatwoot inbox operational. Metabase dashboard connected.

PHASE 1 — Negotiation Agent (Week 3-5)
├── Week 3
│   ├── Day 11-13: LangGraph agent core
│   │   ├── State machine: INTRO → QUALIFY → FAQ → NEGOTIATE → CONFIRM → CLOSE/ESCALATE
│   │   ├── State persistence to Supabase (checkpoint after every transition)
│   │   ├── GPT-4o structured output integration
│   │   ├── Budget guardrail layer (hard-coded, outside LLM)
│   │   ├── System prompts: campaign brief injection, tone, Hinglish support
│   │   └── Unit tests for every state transition
│   │
│   └── Day 14-15: FAQ RAG pipeline
│       ├── pgvector table + embedding pipeline
│       ├── FAQ document chunker + uploader
│       ├── Semantic search endpoint
│       ├── GPT-4o-mini generates answer from retrieved chunks
│       └── Confidence threshold: < 0.7 → "Let me check" → human queue
│
├── Week 4
│   ├── Day 16-17: Negotiation logic + guardrails
│   │   ├── Counter-offer algorithm (midpoint, max 3 rounds, escalate)
│   │   ├── Output validation (rate extraction, profanity check, PII check)
│   │   ├── Input sanitization (prompt injection prevention)
│   │   └── Lead scoring: Cold / Warm / Hot / Rejected
│   │
│   ├── Day 18-19: Human handoff + Slack integration
│   │   ├── n8n workflow: agent → Slack interactive message
│   │   ├── Chatwoot: agent → human assignment
│   │   ├── Human takeover in Chatwoot inbox
│   │   └── Google Sheet status sync on every state change
│   │
│   └── Day 20: Voice fallback agent
│       ├── Twilio Voice + Deepgram STT + ElevenLabs TTS pipeline
│       ├── Same LangGraph FSM, voice-adapted (shorter responses)
│       ├── n8n trigger: 48h no WA response → schedule voice call
│       └── Warm transfer to human if needed
│
├── Week 5
│   ├── Day 21-23: End-to-end testing
│   │   ├── Full flow: Sheet → WA → Negotiate → Handoff → Close → Sheet update
│   │   ├── Edge cases: non-responsive, reject, > max budget, Hinglish, sarcasm
│   │   ├── Voice flow testing
│   │   ├── Load test: 50 concurrent conversations
│   │   └── Quality audit: review 20 AI conversations for tone + accuracy
│   │
│   └── Day 24-25: Polish
│       ├── Error handling, retries, exponential backoff
│       ├── Conversation timeout (auto-follow-up at 24h, 48h, then dormant)
│       └── Metabase: conversation management views
│
│   ✅ DELIVERABLE: Full outreach → negotiate → handoff → close pipeline.

PHASE 2 — IG Monitoring (Week 6-8)
├── Week 6: Instagram Graph API + Phyllo integration + polling n8n workflows
├── Week 7: Tiered sentiment pipeline + anomaly detection + ROI engine
├── Week 8: Metabase dashboard enhancements + testing with real data
│
│   ✅ DELIVERABLE: Live engagement dashboard with sentiment + anomalies.

PHASE 3 — Discovery + Hardening (Week 9-10)
├── Week 9: Modash discovery + dedup + enrichment (n8n workflow)
├── Week 10: Security hardening + documentation + UAT + go-live
│
│   ✅ DELIVERABLE: Production platform, hardened, documented.

Timeline Summary 

WEEK:  1    2    3    4    5    6    7    8    9    10
       ├────┤────├────┤────┤────├────┤────┤────├────┤────┤
Phase 0 ████████
Phase 1           ████████████████
Phase 2                          ████████████████
Phase 3                                           ████████

META VERIFICATION ████████████░░░░  (parallel)

TOTAL: 10 weeks to production MVP

13. Team Structure

Revised for open-source leverage — smaller team needed:

Role Count Responsibilities
Tech Lead / Architect 1 System design, code reviews, n8n workflow design, integration decisions
Backend/AI Engineer (Python) 1 LangGraph agent, FastAPI, guardrails, voice pipeline, sentiment pipeline
Integrations Engineer (Node.js/Python) 1 n8n workflows, Chatwoot config, Sheets sync, IG polling, Modash integration
QA + DevOps 0.5 (shared) E2E testing, Railway deployment, monitoring

Total: 3.5 FTE for 10 weeks (down from 4.25 in v1 — open-source tooling saves ~0.75 FTE)

14. Assumptions, Dependencies & Out of Scope

14.1 Client Responsibilities

  • Provide Google Sheet with influencer data (name, WhatsApp, category, followers, IG handle) — Week 1
  • Initiate Meta Business verification + WhatsApp Business API access — Week 1
  • Provide campaign briefs, FAQ docs, product details, budget bands — before Phase 1
  • Coordinate influencer consent for IG Graph API permissions
  • Designate Slack channel + assign lead follow-up team

14.2 Assumptions

  • ≥60% of influencers have WhatsApp numbers
  • IG Graph API accessible for meaningful subset (Business/Creator accounts)
  • Phyllo/Modash subscriptions approved ($200-500/mo)
  • LLM API costs budgeted separately
  • Cloud hosting approved (~$100-300/mo)

14.3 Out of Scope (v1)

  • CRM integration (Salesforce, HubSpot) — Chatwoot + Sheets serves as v1 CRM
  • YouTube, TikTok, Twitter monitoring — IG only
  • Contract generation / e-signature
  • Payment processing / invoicing
  • Custom mobile app — web only
  • Multi-language beyond English + Hindi/Hinglish

15. Open-Source Tooling Map — Build vs. Reuse

This is the key section. For every component, we evaluate: should we build it, or use an existing open-source project?

15.1 Recommended Open-Source Repos

Component Repo Stars License What It Does Our Usage Build vs. Reuse
Workflow Orchestration n8n-io/n8n 52K+ Sustainable Use Visual workflow automation with 400+ integrations All scheduling, triggers, retries, Sheet sync, Slack alerts ✅ REUSE — saves ~2 weeks of custom scheduler code
Conversation Inbox chatwoot/chatwoot 21K+ MIT Omnichannel customer messaging platform WhatsApp conversation UI, agent assignment, conversation history ✅ REUSE — saves ~3 weeks of custom chat UI
Analytics Dashboard metabase/metabase 40K+ AGPL-3.0 Business intelligence / dashboard builder v1 IG engagement dashboard, campaign reports ✅ REUSE for v1 — ship in 2 days; build custom v2 later if needed
Sentiment Analysis cardiffnlp/twitter-xlm-roberta-base-sentiment-multilingual 10.8M DL CC-BY-4.0 Multilingual social media sentiment classification Tier 1 bulk sentiment on comments ✅ REUSE — free, accurate, multilingual
WhatsApp Dev Sandbox EvolutionAPI/evolution-api 2K+ Apache 2.0 Self-hosted WhatsApp HTTP API Local dev/testing without Meta API quota ✅ REUSE for dev — don't use in production
WhatsApp Dev Sandbox (alt) devlikeapro/waha 3K+ Custom Self-hosted WhatsApp REST API Alternative to Evolution API ✅ REUSE for dev — choose based on team preference
Vector Store for FAQ pgvector (Supabase-native) Built into Supabase PostgreSQL License Vector similarity search in PostgreSQL FAQ RAG retrieval ✅ REUSE — zero extra infra; already in our DB
Chatbot Builder (alternative) baptisteArno/typebot.io 8K+ AGPL-3.0 No-code visual chatbot builder with WhatsApp Could replace LangGraph for simpler flows ❌ SKIP — too limited for our negotiation FSM
Agent Framework langchain-ai/langgraph 10K+ MIT Graph-based LLM agent framework with state machines Negotiation state machine — our core IP ✅ REUSE (it's our agent framework)
WA+LangGraph Reference lucasboscatti/Whatsapp-Langgraph-Agent-Integration ~87 MIT WhatsApp AI agent powered by LangGraph Reference implementation — study their WA webhook + LangGraph integration pattern 📖 REFERENCE — don't use directly, but copy patterns
Influencer Platform (reference) ManojSravan/influencer-marketing-platform Small — Product engineering for influencer brand network Reference for data model and workflow design 📖 REFERENCE — study schema, don't fork
Instagram Scraping (caution) instaloader/instaloader 8K+ MIT Download Instagram photos and metadata Supplementary data collection for public profiles ⚠️ USE WITH CAUTION — violates IG ToS; only for research/enrichment, not production polling

15.2 What We Build Custom (Core IP)

Component Why Custom
LangGraph Negotiation FSM This is the product's core value. No off-the-shelf tool does multi-turn rate negotiation with budget guardrails, human handoff, and WhatsApp integration.
Budget Guardrail Layer Security-critical; must be tailored to our specific rate validation + prompt injection prevention logic.
Campaign-specific prompt engineering System prompts for each negotiation phase, campaign brief injection, tone calibration for Indian market.
Content-matching post detection Image similarity matching for detecting campaign posts without hashtags — novel approach, no OSS tool for this specific use case.
ROI calculation engine CPE, CPR, EMV formulas tuned to influencer marketing; lightweight custom code.

15.3 Decision Framework 

For any new feature, ask:
1. Is there an OSS repo with >1K ⭐ that does 80%+ of what we need?
   YES → REUSE (fork if needed, contribute back)
   NO  → Continue

2. Is there a reference implementation we can study?
   YES → REFERENCE (copy patterns, adapt to our stack)
   NO  → Continue

3. Does this component constitute core IP / competitive advantage?
   YES → BUILD CUSTOM
   NO  → Use simplest possible glue code

16. Competitive Landscape & Market Intel

(Synthesized from Grok research — X posts, Reddit, reviews, late 2025-early 2026)

16.1 Direct Competitors

Competitor What They Do Strengths Weaknesses vs. Our Platform
Janney AI AI agent for discovery + inbox outreach + rate negotiation End-to-end; claims 30-45% savings on partnerships Email/inbox only — no WhatsApp; no voice; no IG monitoring dashboard
Influencer Hero AI-powered discovery + auto-messages + campaign prediction Affordable; good CRM; automations Not a conversational agent — templates only; no real-time negotiation
Grin Full platform — discovery + outreach + tracking + payments Enterprise-grade; Shopify integration Expensive; complex; creators must authenticate; billing surprises
AspireIQ (now Aspire) Similar to Grin Strong marketplace Steep learning curve; overkill for smaller teams
ManyChat IG DM + comment-to-DM automation Great for IG DMs; easy setup No WhatsApp negotiation; no campaign monitoring; rule-based, not AI

16.2 Our Differentiation

Capability Janney AI Grin/Aspire ManyChat Our Platform
WhatsApp as primary channel ❌ ❌ ❌ ✅
AI voice agent fallback ❌ ❌ ❌ ✅
Real-time rate negotiation ✅ (email) ❌ ❌ ✅ (WhatsApp + voice)
Hard budget guardrails in code Unknown ❌ ❌ ✅
IG engagement dashboard ❌ ✅ ❌ ✅
Sentiment analysis on comments ❌ Basic ❌ ✅ (tiered, multilingual)
Anomaly detection ❌ ❌ ❌ ✅
Hindi/Hinglish support ❌ ❌ ❌ ✅
Google Sheets as CRM ❌ ❌ ❌ ✅ (client's existing workflow)
Open-source components ❌ ❌ ❌ ✅ (lower lock-in, lower cost)

16.3 Market Sentiment Summary

  • "Future is agents, not more tools" — brands want AI that acts, not just dashboards to look at
  • Human-in-the-loop is non-negotiable — pure automation without human oversight erodes relationships
  • Personalization is king — reference specific posts/content in outreach, not just "Hi {name}"
  • India market opportunity — WhatsApp dominant, regional language support is a gap in existing tools
  • Price sensitivity — smaller teams reject annual contracts and enterprise pricing; our ~$329/mo at 100 influencers is highly competitive vs. Grin ($$$) or CreatorIQ ($$$$)

17. Appendix — Tech Lead Review

✅ Agreements (unchanged from v1)

Proposal Status
Graph API as primary IG data source ✅ Agreed
Permission dependency is a real blocker ✅ Agreed — solved with dual-layer
Slack for human handoff + Sheet status updates ✅ Agreed
Google Sheets as CRM in v1 ✅ Agreed
Discovery workflow every 2-3 days ✅ Agreed
Deduplicate on IG handle ✅ Agreed

🔄 Divergences (expanded from v1)

Tech Lead Said Our Position Why
Phyllo OR Graph API Both — dual-layer Graph API free + Phyllo fills gaps
Twilio for WhatsApp Cloud API direct; Twilio only for voice 10-15% savings; direct template control
No AI framework specified LangGraph + hard-coded guardrails Deterministic FSM; budget caps enforced in code
No anomaly detection Modified Z-Score Proactive campaign management
No post detection strategy Triple detection (hashtag + mention + image similarity) Catches lazy influencers
No mention of orchestration engine n8n (self-hosted) Saves 2 weeks of scheduler code
No mention of conversation inbox Chatwoot (self-hosted) Saves 3 weeks of chat UI code
No mention of FAQ system pgvector RAG in Supabase Accurate FAQ answers; prevents hallucination

18. Appendix — API Rate Limits

API Limit Our Usage Headroom
WhatsApp Cloud API 250→1K→10K/day (tier-based) Pace at 50/hr 5× at tier 2
Instagram Graph API 200 calls/user/hour 6 polls/day × 100 influencers 95% under limit
OpenAI GPT-4o 10K RPM (Tier 3) Peak: ~100 RPM 100× headroom
Google Sheets API 300 req/min ~10/min batched 30× headroom
Slack API 20 msg/min/channel Peak: 5/min 4× headroom
HuggingFace Inference API 30K char/min (free) ~10K char/batch 3× headroom
Phyllo API ~100/min ~0.13/min Massive

19. Appendix — Glossary

Term Definition
BSP Business Solution Provider — third-party WhatsApp API mediator (Twilio, WATI, 360dialog)
CPE Cost per Engagement
CPR Cost per Reach
EMV Estimated Media Value
FSM Finite State Machine
RAG Retrieval-Augmented Generation — LLM answers grounded in retrieved documents
RLS Row-Level Security (Supabase/PostgreSQL)
STT Speech-to-Text
TTS Text-to-Speech
Template Message Pre-approved WhatsApp format for business-initiated conversations
Conversation Window 24-hour period after user replies allowing free-form messages

20. Next Steps

# Action Owner Timeline
1 Product team reviews this TDD and approves scope Product Week 0
2 Commercial proposal finalized based on TDD Tech Lead + Sales Week 0
3 Client initiates Meta Business verification Client Day 1 (critical path)
4 Client provides Google Sheet with sample influencer data Client Week 1
5 Client provides campaign brief + FAQ docs + budget bands Client Before Phase 1
6 Engineering kickoff upon contract signature Eng Team Week 1

This document is intended for internal review and scoping. Estimates subject to revision based on client requirements, API access timelines, and agreed scope.

End of Technical Design Document v2.0

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support