docs/workflows.md

MicProtocol – Domain Workflows

Guest Booking State Machine

The core workflow manages a guest through the complete lifecycle, from initial prospecting through post-publication promotion.

stateDiagram-v2
    [*] --> Prospecting: Add to pipeline
    Prospecting --> AI_Research: Enrich data
    AI_Research --> Ready_To_Contact: Verify email/social
    
    Ready_To_Contact --> Outreach_Sent: Trigger sequence
    Outreach_Sent --> Opened: Email opened
    Outreach_Sent --> Bounced: Invalid email
    
    Opened --> Replied: Guest responds
    Opened --> No_Response: 3 days passed
    
    No_Response --> Followup_1: Auto-send
    No_Response --> Followup_2: 5 days later
    No_Response --> Snoozed: Manual action
    
    Replied --> Interested: Positive intent
    Replied --> Declined: Rejection
    Replied --> Questions: Needs info
    
    Interested --> Scheduling_Link_Sent: Generate slot options
    Scheduling_Link_Sent --> Time_Selected: Guest picks
    Time_Selected --> Confirmed: Calendar synced
    Confirmed --> Pre_Production: Buffer period
    
    Pre_Production --> Assets_Collected: All requirements met
    Assets_Collected --> Recorded: Episode complete
    Recorded --> Post_Production: Editing
    
    Post_Production --> Published: Live
    Published --> Promotion_Active: Share clips
    Promotion_Active --> Completed: Archive
    
    Declined --> [*]
    Snoozed --> Ready_To_Contact: Reactivate
    Bounced --> [*]

State Transition Rules

From	To	Trigger	Side Effects
Prospect	Contacted	Outreach sequence starts	lastContactAt updated, email queued
Contacted	Scheduled	Booking confirmed	Calendar event created, reminder queued
Scheduled	Recorded	Host marks complete	Asset validation triggered
Recorded	Published	Episode goes live	Promo tasks generated

---

Asset Collection Sequence

The asset pipeline automates pre-production material gathering from guests, with daily reminders and AI-powered validation.

sequenceDiagram
    participant B as BullMQ Worker
    participant E as Episode Service
    participant G as Guest Portal
    participant S as Storage (R2)
    participant AI as AI Processing

    B->>E: Trigger 7 days before recording
    E->>E: Generate asset requirements from template
    E->>G: Create secure upload portal (unique token)
    E->>G: Send notification email with portal link

    loop Daily Reminder Check
        B->>E: Check completion status
        alt Incomplete assets
            B->>G: Send reminder email
        else All complete
            B->>E: Mark "Ready to Record"
        end
    end

    G->>S: Guest uploads headshot
    S->>AI: Trigger background removal + resolution check
    AI->>S: Save processed version
    AI->>E: Update submission status

    G->>S: Guest uploads intro audio
    S->>AI: Transcribe via Whisper
    AI->>AI: Verify host name pronunciation
    AI->>E: Update submission with transcript

    G->>E: Submit social links
    E->>E: Validate links are active

    E->>B: All assets collected → mark episode ready
    B->>E: Notify host via WebSocket

Asset Types & Validation

Asset Type	Format	Validation
Headshot	PNG/JPG ≥1200×1200	Face detection, background removal, resolution check
Bio	Text, 2-3 sentences	Length check, grammar validation
Intro Audio	MP3/WAV, 15-30s	Whisper transcription, quality analysis
Social Links	URLs	HTTP status check, public accessibility
Talking Points	Text/Markdown	Keyword extraction for show notes

---

Outreach Automation Flow

flowchart TD
    START([Guest Added as Prospect]) --> ENRICH[AI Enrichment]
    ENRICH --> |LinkedIn, Twitter, Blog| RESEARCH[Build Guest Profile]
    RESEARCH --> SCORE[Calculate Priority Score]
    
    SCORE --> |Score ≥ 70| HIGH_PRI[High Priority Queue]
    SCORE --> |Score 40-69| MED_PRI[Medium Priority Queue]
    SCORE --> |Score < 40| LOW_PRI[Low Priority Queue]
    
    HIGH_PRI --> PERSONALIZE[AI Personalized Outreach]
    MED_PRI --> TEMPLATE[Template-based Outreach]
    LOW_PRI --> BATCH[Batch Outreach]
    
    PERSONALIZE --> SEND_INITIAL[Send Initial Email]
    TEMPLATE --> SEND_INITIAL
    BATCH --> SEND_INITIAL
    
    SEND_INITIAL --> TRACK[Track Opens & Clicks]
    
    TRACK --> |Opened, No Reply| WAIT3[Wait 3 Days]
    TRACK --> |Not Opened| WAIT5[Wait 5 Days]
    TRACK --> |Replied| CLASSIFY[Classify Response via AI]
    
    WAIT3 --> FOLLOWUP1[Send Followup #1]
    WAIT5 --> FOLLOWUP2[Send Followup #2]
    
    FOLLOWUP1 --> TRACK
    FOLLOWUP2 --> TRACK
    
    CLASSIFY --> |Positive| BOOKING[Send Booking Link]
    CLASSIFY --> |Negative| ARCHIVE[Archive & Tag]
    CLASSIFY --> |Question| ALERT[Alert Host]
    
    BOOKING --> SCHEDULED([Guest Scheduled])

---

Episode Production Pipeline

flowchart LR
    DRAFT[Draft] --> SCHEDULE[Scheduled]
    SCHEDULE --> |7 days before| ASSET_REQ[Asset Collection]
    ASSET_REQ --> |All assets in| READY[Ready to Record]
    READY --> RECORD[Recorded]
    RECORD --> EDIT[Editing]
    EDIT --> PUBLISH[Published]
    PUBLISH --> PROMOTE[Promotion]
    
    style DRAFT fill:#DFE6E9
    style SCHEDULE fill:#74B9FF
    style ASSET_REQ fill:#FDCB6E
    style READY fill:#00B894
    style RECORD fill:#A29BFE
    style EDIT fill:#FDCB6E
    style PUBLISH fill:#6C5CE7
    style PROMOTE fill:#FD79A8