Key Data Flows

1. Inbound Voice Call (AI-Handled)

sequenceDiagram
    participant Caller
    participant LK_SIP as LiveKit SIP Gateway
    participant LiveKit
    participant CallService as Call Service
    participant Atlas as Atlas (Adapter)
    participant MediaBot as Media Bot
    participant Compass
    participant STT
    participant LLM
    participant TTS
    participant Billing

    alt WebRTC
        Caller->>LiveKit: Connect (WebRTC)
    else SIP / PBX / 3CX
        Caller->>LK_SIP: Inbound SIP call
        LK_SIP->>LiveKit: Bridge to room
    end

    LiveKit->>CallService: Webhook — participant joined
    CallService->>CallService: Resolve agent_id, create room
    CallService->>LiveKit: Manual dispatch — Atlas
    CallService->>LiveKit: Manual dispatch — Media Bot
    LiveKit->>Atlas: Join room (agent_id in metadata)
    LiveKit->>MediaBot: Join room

    Atlas->>Compass: GET /agents/{agent_id}
    Compass-->>Atlas: Agent config (prompt, tools, voice, etc.)
    MediaBot->>Caller: Play ringback tone

    loop Conversation turn
        Caller->>Atlas: Audio
        Atlas->>STT: Audio stream
        STT-->>Atlas: Transcript
        Atlas->>LLM: Transcript + context
        LLM-->>Atlas: Response text
        Atlas->>TTS: Response text
        TTS-->>Atlas: Audio
        Atlas->>Caller: Audio
        MediaBot->>MediaBot: Transcribe + sentiment (parallel)
    end

    Atlas->>Billing: Publish call data (post-call)

2. Inbound WhatsApp Message

sequenceDiagram
    participant Contact
    participant Meta
    participant WAS as WhatsApp Service
    participant Herald
    participant Notify as Notification Service
    participant AD as Agent Desktop

    Contact->>Meta: WhatsApp message
    Meta->>WAS: POST /meta/webhook
    WAS->>WAS: Store message, lookup AgentPhoneMapping

    alt AI-handled (aiAgentId mapped)
        WAS->>Herald: POST /turn (message + conversation context)
        Herald-->>WAS: POST /reply (event=typing)
        WAS->>Meta: Send typing indicator
        Herald-->>WAS: POST /reply (event=message, text=...)
        WAS->>Meta: Send AI reply
        Meta->>Contact: WhatsApp reply
        Herald-->>WAS: POST /reply (event=done, escalate=false)
        WAS->>WAS: Update conversation summary
    else Human-handled (teamId mapped or escalate=true)
        WAS->>Notify: Notify agent team
        Notify->>AD: Push notification
        AD->>WAS: Claim + reply
        WAS->>Meta: Send agent reply
        Meta->>Contact: WhatsApp reply
    end

3. Agent Provisioning (Compass)

sequenceDiagram
    participant Atlas
    participant Compass
    participant DB as Config Store

    Atlas->>Compass: GET /agents/{agent_id}
    Compass->>DB: Fetch agent record
    DB-->>Compass: Agent config
    Compass-->>Atlas: Agent details\n(system prompt, voice model,\ntools, language, etc.)

4. Post-Call Billing

sequenceDiagram
    participant Atlas
    participant Billing

    Atlas->>Billing: Publish call data\n(duration, agent_id, channel, transcript ref)
    Billing->>Billing: Calculate cost
    Billing->>Billing: Store record