ClinicFlow AI — AI Receptionist & Appointment Automation

graph TB
    subgraph Patients["Patient Channels"]
        P1[📞 Phone Call]
        P2[💬 WhatsApp]
    end

    subgraph Telephony["Telephony Layer"]
        T1[Exotel — India]
        T2[Twilio — UAE]
    end

    subgraph AI["AI Core — FastAPI + LangGraph"]
        V[Voice Server<br/>WebSocket Stream]
        STT[Deepgram STT<br/>Nova-2]
        LLM[GPT-4o-mini<br/>LangGraph Agent]
        TTS[Cartesia TTS<br/>< 100ms latency]
        WA[WhatsApp AI<br/>Worker]
    end

    subgraph Queue["Queue Layer — BullMQ + Redis"]
        Q1[whatsapp-ai-response<br/>Priority: HIGH]
        Q2[voice-realtime<br/>Priority: CRITICAL]
        Q3[appointment-reminders<br/>Cron scheduled]
        Q4[missed-call-recovery<br/>5 min delay]
    end

    subgraph Backend["Backend API — FastAPI"]
        API[REST API Gateway<br/>JWT + Tenant Resolution]
        BOOK[Booking Engine<br/>No double-booking]
        CRM[CRM Service]
        NOTIF[Notification Service]
    end

    subgraph DB["Persistence"]
        PG[(PostgreSQL<br/>Primary DB)]
        RD[(Redis<br/>Cache + Sessions)]
    end

    subgraph Dashboard["Frontend — Next.js 14"]
        DASH[CRM Dashboard<br/>Real-time]
        ANA[Analytics<br/>Charts]
    end

    P1 --> T1 & T2
    T1 & T2 --> V
    V --> STT --> LLM --> TTS --> V
    LLM --> API
    P2 --> Q1 --> WA --> LLM
    API --> BOOK --> PG
    API --> NOTIF --> Q3 & Q4
    BOOK --> RD
    CRM --> PG
    DASH --> API
    ANA --> API

erDiagram
    TENANTS {
        uuid id PK
        varchar name
        varchar slug UK
        varchar plan
        varchar phone_number
        varchar whatsapp_number
        varchar timezone
        jsonb business_hours
        varchar country
        boolean ai_enabled
        boolean is_active
        timestamptz trial_ends_at
        timestamptz created_at
    }

    USERS {
        uuid id PK
        uuid tenant_id FK
        varchar email UK
        varchar name
        varchar role
        boolean is_active
        timestamptz last_login_at
    }

    PRACTITIONERS {
        uuid id PK
        uuid tenant_id FK
        varchar name
        varchar specialty
        boolean is_active
    }

    PATIENTS {
        uuid id PK
        uuid tenant_id FK
        varchar name
        varchar phone
        varchar whatsapp
        varchar email
        text[] tags
        text notes
        varchar source
        timestamptz created_at
    }

    SERVICES {
        uuid id PK
        uuid tenant_id FK
        varchar name
        int duration_minutes
        int buffer_minutes
        decimal price_min
        decimal price_max
        boolean is_active
    }

    APPOINTMENTS {
        uuid id PK
        uuid tenant_id FK
        uuid patient_id FK
        uuid practitioner_id FK
        uuid service_id FK
        uuid call_log_id FK
        timestamptz scheduled_at
        timestamptz ends_at
        int duration_minutes
        varchar status
        varchar booked_by
        boolean reminder_24h_sent
        boolean reminder_2h_sent
        timestamptz created_at
    }

    CALL_LOGS {
        uuid id PK
        uuid tenant_id FK
        uuid patient_id FK
        varchar caller_number
        varchar direction
        varchar status
        int duration_seconds
        varchar outcome
        text transcript
        text recording_url
        text ai_summary
        uuid appointment_id FK
        timestamptz started_at
        timestamptz ended_at
    }

    CONVERSATIONS {
        uuid id PK
        uuid tenant_id FK
        uuid patient_id FK
        varchar wa_phone
        varchar channel
        varchar status
        varchar assigned_to
        timestamptz last_message_at
    }

    TENANTS ||--o{ USERS : "has"
    TENANTS ||--o{ PRACTITIONERS : "has"
    TENANTS ||--o{ PATIENTS : "has"
    TENANTS ||--o{ SERVICES : "has"
    TENANTS ||--o{ APPOINTMENTS : "has"
    TENANTS ||--o{ CALL_LOGS : "has"
    TENANTS ||--o{ CONVERSATIONS : "has"
    PATIENTS ||--o{ APPOINTMENTS : "books"
    PATIENTS ||--o{ CALL_LOGS : "generates"
    PATIENTS ||--o{ CONVERSATIONS : "has"
    PRACTITIONERS ||--o{ APPOINTMENTS : "attends"
    SERVICES ||--o{ APPOINTMENTS : "defines"
    APPOINTMENTS ||--o| CALL_LOGS : "originates from"

flowchart TD
    START([📞 Inbound Call / 💬 WhatsApp Message]) --> GREET

    GREET["🗣️ GREETING\nAI answers in < 1 second\nClinic name + warm welcome"] --> INTENT

    INTENT{"🧠 INTENT DETECTION\nGPT-4o-mini classifies"}

    INTENT --> BOOK["📅 BOOKING FLOW"]
    INTENT --> FAQ["❓ FAQ FLOW"]
    INTENT --> RESCHEDULE["🔄 RESCHEDULE FLOW"]
    INTENT --> CANCEL["❌ CANCELLATION FLOW"]
    INTENT --> EMERGENCY["🚨 EMERGENCY FLOW"]

    BOOK --> CN["Collect Name"]
    CN --> CP["Collect Phone"]
    CP --> CT["Collect Treatment Type"]
    CT --> CD["Collect Preferred Date"]
    CD --> CA{"API: check_availability()"}
    CA -->|Slots available| OFFER["Offer 3 Slots"]
    CA -->|No slots| NEXT["Suggest Next Available Day"]
    NEXT --> OFFER
    OFFER --> CONFIRM["Patient Confirms Slot"]
    CONFIRM --> CREATE{"API: create_appointment()"}
    CREATE -->|Success ✅| NOTIFY["Send Confirmation\nSMS + WhatsApp"]
    NOTIFY --> CLOSE(["✅ Call Complete\nCRM updated"])
    CREATE -->|Failure ❌| RETRY["Offer Alternative Slot"]
    RETRY --> OFFER

    FAQ --> KB["Query Knowledge Base\nClinic hours, pricing ranges,\nlocation, parking"]
    KB --> ANSWER["Deliver Answer < 3 sentences"]
    ANSWER --> OFFER_BOOK{"Offer to Book?"}
    OFFER_BOOK -->|Yes| BOOK
    OFFER_BOOK -->|No| CLOSE

    RESCHEDULE --> LOOKUP{"API: get_appointment_by_phone()"}
    LOOKUP -->|Found| OLD_CANCEL["Cancel Old Slot"]
    OLD_CANCEL --> CA
    LOOKUP -->|Not found| HUMAN

    CANCEL --> VERIFY["Verify Appointment"]
    VERIFY --> CONF_CANCEL{"Confirm Cancellation Intent"}
    CONF_CANCEL -->|Confirmed| DO_CANCEL{"API: cancel_appointment()"}
    DO_CANCEL --> REBOOK["Offer to Rebook"]
    CONF_CANCEL -->|Declined| CLOSE

    EMERGENCY --> XFER["⚡ Immediate Transfer\nProvide emergency number"]

    INTENT -->|2 failed detections| HUMAN
    INTENT -->|Frustration detected| HUMAN
    HUMAN["👤 HUMAN HANDOFF\nWarm transfer if receptionist available\nTake message + callback promise if not"] --> CLOSE

    style EMERGENCY fill:#ff4444,color:#fff
    style HUMAN fill:#ff8800,color:#fff
    style CLOSE fill:#22c55e,color:#fff
    style CREATE fill:#3b82f6,color:#fff
    style CA fill:#3b82f6,color:#fff