Phase 1: Discovery & User Journeys

Last Updated: 2026-03-31 Status: Draft

1. Context & Goal

The Chat Engine (Omnichannel AI Chatbot Platform) is a powerful, integrated service offered to LogicSpike Tenants (Business Owners, E-commerce, Agencies). It allows them to instantly provision a custom-trained AI chatbot and deploy it across multiple communication channels (Website Widget, WhatsApp, Telegram, Email) to provide 24/7 automated customer support and lead generation.

Crucially, it provides a centralized Unified Inbox within the LogicSpike dashboard where business owners can monitor AI conversations, view leads captured by the AI, and seamlessly take over chats when human assistance is required.

System Flow Overview

2. Actors

3. Core User Journeys

Journey A: First-Time Setup — "Training the AI & Persona"

Persona: Rahul, owner of a localized SaaS company. Goal: Provide the platform with company context and define the bot's tone so it represents his brand accurately.

1. Trigger: Rahul navigates to Dashboard → Chat Engine → Setup.
2. Action:
   • Sets the Bot Persona: "Your name is Sarah. Be highly professional but warm. Always offer to book a demo."
   • Chooses "Scrape Website" and enters https://his-company.com/faq.
   • Chooses "Upload PDF" and uploads his pricing guide.
   • Sets Lead Capture: "Ask for the user's email before answering pricing questions."
   • Clicks "Train Bot".
3. Backend Operations:
   • Crawler fetches the website text. Text extractor reads the PDF.
   • Content is chunked and sent to an embedding model (e.g., text-embedding-004).
   • Vectors are stored in the vector database (pgvector) tagged with Rahul's tenant_id.
   • Bot configuration (persona prompt, lead rules) is saved in bot_configs.
4. Outcome: The AI is now ready to behave as "Sarah" with full knowledge of Rahul's business.

Journey B: Connecting Channels — "Omnichannel Deployment"

Persona: Rahul wants his customers to chat via his Website and WhatsApp. Goal: Enable the AI to receive and reply to messages from different platforms.

1. Trigger: Rahul navigates to Dashboard → Chat Engine → Channels.
2. Action:
   • Clicks "Enable Website Widget". The system generates a <script> tag. Rahul copies this to his website.
   • Clicks "Connect WhatsApp Business". He goes through the Meta OAuth Flow or provides API credentials.
   • Status updates to Active for both channels.
3. Backend Operations:
   • System registers /webhooks/whatsapp/{tenant_id} with Meta's API.
   • Generates a secure widget_token locked to Rahul's domain origin.
4. Outcome: The chatbot is now live on the website and WhatsApp simultaneously.

Journey C: Lead Capture & AI Support — "The 2AM Customer"

Persona: Priya, watching Rahul's website at 2:00 AM. Goal: Get immediate pricing info, resulting in Priya becoming a qualified lead.

1. Trigger: Priya sends a WhatsApp message to Rahul's business number: "How much is the enterprise plan?"
2. Action:
   • Bot ("Sarah") responds: "Hi there! I'd love to help you with our Enterprise pricing. First, could I get your email address so we can send you our detailed brochure?"
   • Priya replies: "priya@example.com"
   • Bot saves the lead and responds: "Thank you, Priya! Our Enterprise plan starts at $499/mo and includes priority support. Would you like to schedule a demo?"
3. Backend Operations:
   • Chat Orchestrator evaluates the incoming message against Lead Capture rules.
   • Recognizing an email, it updates the chat_contacts table, linking this WhatsApp number to priya@example.com.
   • AI then performs a similarity search on pgvector, fetches the pricing context, and generates the final reply.
4. Outcome: Priya gets an instant, accurate answer, and Rahul wakes up to a captured, qualified lead.

Journey D: Human Handoff — "Taking Over When AI Fails"

Persona: Amit (Customer) and Rahul (Human Agent). Goal: Seamlessly transition from AI to Human without the customer noticing a broken experience.

1. Trigger: Amit asks a highly specific account-level question: "Why was my card charged twice yesterday?"
2. Action (System):
   • The AI recognizes it cannot access billing info securely (or Amit clicks a "Talk to Human" button).
   • AI replies: "I don't have access to your personal billing information, but I am connecting you to our support team right now. They'll be right with you."
3. Action (Human):
   • Rahul receives a desktop notification: "🚨 Human Required: WhatsApp (Amit)".
   • Rahul clicks it, opening the Unified Inbox. He reads the AI conversation history.
   • Rahul types: "Hi Amit, I've looked at your account. I'll issue a refund for the duplicate charge now."
4. Backend Operations:
   • chat_sessions.status transitions from ai_handled to human_escalated.
   • The Webhook Hub pauses sending Amit's messages to the LLM.
   • Rahul's manual replies are pushed directly to the WhatsApp API.
5. Outcome: Complex issues are resolved exactly when necessary without frustrating the user with AI hallucinations.

Journey E: Continuous Learning — "Fixing Knowledge Gaps"

Persona: Rahul reviewing the week's performance. Goal: Improve the AI's accuracy by seeing what it got wrong and teaching it new answers.

1. Trigger: Rahul opens Dashboard → Chat Engine → Analytics & Insights.
2. Action:
   • Views a chart: "75 chats handled by AI, 5 escalated to Human".
   • Clicks on the "Escalated" list and reviews a chat where a customer asked, "Do you have an affiliate program?" and the AI failed.
   • Rahul clicks "Add to Knowledge Base" next to that question.
   • A modal opens where he types the correct answer: "Yes, we offer a 20% recurring commission..." and saves.
3. Backend Operations:
   • A new Q&A pair is converted into an embedding and pushed to pgvector.
4. Outcome: The AI gets incrementally smarter over time based on real conversations.

Journey F: Website Widget Experience — "The First Impression"

Persona: Priya, browsing a SaaS website at midnight. Goal: Get instant help without leaving the page.

1. Trigger: Priya lands on https://rahuls-saas.com/pricing. A small bubble appears in the bottom-right corner with a wave animation: "Hi! 👋 Got questions? I'm Sarah, your AI assistant."
2. Action:
   • Priya clicks the bubble. A sleek chat window slides up.
   • She types: "Is there a free trial?"
   • The typing indicator animates for ~1 second, then tokens stream in letter by letter: "Yes! We offer a 14-day free trial with no credit card required. Would you like me to walk you through how to get started?"
   • Priya scrolls the widget down and sees a small "Powered by LogicSpike" footer.
3. Backend Operations:
   • The <script> tag loaded a lightweight iframe from widget.logicspike.com.
   • The iframe validated the X-Widget-Token against the origin domain.
   • The message was sent via POST /chat/widget/message and the response streamed back via Server-Sent Events (SSE).
   • A new anonymous CustomerContact was created with only sessionId as identity.
4. Outcome: Priya gets an instant, premium chat experience that feels native to the website. The business owner didn't write a single line of code beyond pasting a <script> tag.

Journey G: Weekly Analytics Review — "Measuring the AI ROI"

Persona: Rahul reviewing Sunday morning performance. Goal: Understand whether the AI is saving time and capturing leads effectively.

1. Trigger: Rahul opens Dashboard → AI Assistant → Analytics.
2. Action:
   • KPI Cards: Shows "1,240 chats handled by AI this week", "Human Handoff Rate: 4%", "45 new leads captured", "Average Response Time: 1.2s".
   • Resolution Chart: A stacked bar chart shows daily breakdown of AI-resolved vs. Human-resolved vs. Abandoned conversations.
   • Top Unanswered Questions: A ranked list of questions the AI could not answer (triggered [[HANDOFF]]). Each row has an "Add to Knowledge Base" shortcut button.
   • Lead Funnel: Shows conversion: Visitors → Chatted → Email Captured → Demo Booked.
3. Backend Operations:
   • Aggregated from chat_sessions (status transitions) and chat_messages (intent classification).
   • The "Top Unanswered Questions" list is built from sessions where status transitioned to human_escalated and the last AI message contained the handoff trigger.
4. Outcome: Rahul identifies 3 new questions the AI failed on, adds answers to the Knowledge Base, and next week's handoff rate drops to 2%.

4. Edge Cases / Error Paths