# QuitSure AI Support Chatbot: Architecture and Integration Design **Prepared for:** Kriti (CTO), for technical review and approval **Scope:** how the AI support assistant is designed and how it integrates with the QuitSure app and the existing Freshchat coaching flow. --- ## 1. Overview An in-app AI support assistant. The user opens the chat and talks to the AI first. The AI answers support, subscription, and program questions instantly from QuitSure's approved knowledge. When it cannot answer, or the user asks for a person, it hands the conversation to a human coach in Freshchat, along with a written summary so the coach has full context. The AI service is a standalone stateless HTTP API. The app owns the chat UI and the Freshchat handoff. The AI service never touches Freshchat directly. --- ## 2. The AI brain (overview) The assistant is built on retrieval-augmented generation (RAG), grounded strictly in approved content: - **Knowledge base:** QuitSure's approved "Chat Shortcuts" content (~490 curated Q&A entries), not the open internet and not raw coach transcripts. Answers come only from this approved material. - **Retrieval:** for each user message, the most relevant approved answers are retrieved using a hybrid of semantic (embedding) and keyword search, filtered to the user's program and platform. - **Generation:** a Gemini model composes the reply strictly from those retrieved answers, in the user's language (English, Hindi, Hinglish, and others). - **Program and stage aware:** answers adapt to the user's program (Original / Relaxed) and current day, so stage-specific concepts are only shared when appropriate. - **Layered safety (no hallucination):** a retrieval-confidence floor (abstain if nothing relevant), strict grounding instructions, a deterministic self-harm gate, and an anti-hallucination backstop. When unsure, it escalates rather than guessing. - **Escalation:** the response always carries a decision, either answer or escalate with a reason (cannot answer, medical beyond the approved content, self-harm/crisis, user asked for a human, frustration, or an account action needing a human). The service is stateless: it holds no session memory. The app passes the recent conversation on each request. --- ## 3. User flow **Entry.** The user taps the chat icon. The app makes one decision: > Has this user escalated to a coach in the last 48 hours? > - **Yes** -> open the Freshchat coach thread (continue with the human). > - **No** -> open a fresh AI chat. **In the AI chat.** The user asks; the AI answers, tailored to their program and day. Thumbs up/down on each reply. A "Talk to a coach" option is always available for a one-tap human handoff. The AI escalates automatically when it cannot answer, detects a medical/crisis/frustration case, or the user requests a human. **On escalation.** A coach is assigned in Freshchat, the AI's contextual summary is attached for the coach, and the conversation moves to the Freshchat screen. This starts the 48-hour human window, so a returning user reaches the coach directly. Coaches reply within a few minutes, 24/7. After 48 hours, the next visit starts fresh with the AI. **Crisis.** Any self-harm signal triggers an immediate helpline response and escalation to a human. --- ## 4. App and Freshchat integration - The app calls the AI service at `POST /chat` per user message, sending the message, recent history, and context (program, platform, current day, subscription status). The service returns the answer, an escalate flag, the reason, a routing hint (coaching or technical), a message id (for feedback), and, when escalating, a **contextual summary**. - The **coach summary is a short paragraph**, not a single line: it states what the user asked, what the AI covered or attempted, the user's stage (program and day), and why it is being handed off, so the coach has full context on pickup. - On escalation, the app assigns a coach in Freshchat, attaches the AI summary so it is visible to the coach in their agent view, and routes to the correct team (coaching vs technical). Freshchat remains the human layer; the AI service never posts to Freshchat itself. - Feedback (thumbs up/down) is sent to the AI service to drive continuous improvement of the knowledge. - LeanSure (P11) users are gated off the AI, as the knowledge base is smoking-cessation only. --- ## 5. Data and storage Three distinct kinds of data, stored separately: - **Live conversation:** held by the app during the session and passed to the stateless `/chat` API each turn. Nothing about the live turn is retained by the API itself beyond logging. - **AI conversation history:** stored in our database as a single continuous thread per user, and returned to the app via a `GET /history` endpoint so users can see their past AI chats. Because this is user-facing, messages are stored verbatim and protected by access control and a retention window (not redacted). - **Coach conversations:** held in Freshchat, which is also where the user's coach chat history lives. The same store also powers knowledge improvement (identifying gaps and reviewing feedback). **Schema (two tables):** - A chat-log table: one row per turn (message, answer, program, platform, current day, subscription status, retrieval confidence, escalation flag and reason, timestamp), keyed and indexed by user id and time to serve history. - A feedback table: thumbs rating and optional note, linked to the reply. --- ## 6. Security and data protection (design) - **Authentication:** the app authenticates to the AI service using the app's existing access token (Bearer), verified server-side; a shared key is used for internal and test access. - **Transport:** all calls over HTTPS. - **PII:** conversation data is held on a restricted production database with access limited to the improvement/support role, and a defined retention window after which records are deleted. - **Grounding as a safety property:** because the AI answers only from approved content, it does not surface unapproved medical or policy claims; anything outside that content escalates to a human. --- ## 7. Responsibilities - **App team:** the native AI chat screen, entry routing (the 48-hour rule), the `/chat` integration, the Freshchat handoff with the summary, displaying AI history, feedback, and LeanSure gating. - **AI team:** the AI service and knowledge base, the `/history` endpoint and schema, token verification, data protection and retention, and ongoing knowledge updates. - **Coaches:** no change to how they work; escalations arrive in the existing Freshchat channels, now with an AI summary attached. --- ## 8. Rollout 1. **Validate on the test service.** The app builds the full flow against the existing test deployment and the whole journey is verified end to end (AI answers, escalation, handoff with summary, routing, feedback, gating). 2. **Pilot.** Ship the validated flow to users and observe real usage and feedback. 3. **Production hardening.** Token-based auth, data-protection and retention automation, and dedicated production hosting. The app integration is identical across these steps; only the service URL and auth change. --- ## 9. Key design decisions (rationale) - **RAG over fine-tuning:** content changes frequently; RAG updates instantly by editing the knowledge base, keeps answers grounded, and allows source-level control. No model retraining. - **Stateless API:** the app owns the conversation and passes history; this keeps the service simple and horizontally scalable. - **Single-thread AI history:** support is short, topic-based Q&A; one continuous thread per user is simpler and matches the Freshchat model, versus multi-thread conversation management. - **48-hour handoff window:** Freshchat does not expose a client-readable resolved status, so a time-based window is a reliable, simple way to keep a user with their coach after an escalation. - **AI never touches Freshchat:** the app bridges the two, preserving the rule that no coach transcript data flows into the AI.