# MicProtocol – Domain Workflows

## Guest Booking State Machine

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

```mermaid
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.

```mermaid
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

```mermaid
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

```mermaid
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
```