Frontend & UI Specification

Last Updated: 2026-03-31 Status: Active

This document outlines the detailed user interface structure, page layouts, and component interactions required in the apps/seller-dashboard (Next.js) to manage the Chat Engine.

1. Primary Navigation

The Chat Engine features will live under a new top-level navigation item in the main Dashboard sidebar, labeled "AI Assistant" (or "Omnichannel Hub").

Dashboard
├── Content Engine
├── AI Assistant
│   ├── Overview
│   ├── Unified Inbox (Escalated: 3)
│   ├── Knowledge Base
│   ├── Channels
│   └── Settings & Persona
└── Settings

2. Page Specifications

2.1 Overview (Dashboard Home)

Path: /dashboard/ai-assistant

Purpose: Provide the Workspace Owner with a high-level view of how much time the AI is saving them and how many leads are being generated.

UI Components:

• Hero Metrics Row:
  • Chats Handled by AI: e.g., 1,240 (Up 12% vs last week)
  • Human Handoff Rate: e.g., 4% (Green indicates low failure rate)
  • Leads Captured: e.g., 45 (Emails/Phones collected)
  • AI Credits Remaining: e.g., 85,000 / 100,000 tokens
• Activity Chart: A line chart comparing AI messages vs. Human messages over the last 30 days.
• Recent Leads Table: A quick-view table of CustomerContact entities recently generated by the bot, showing Name, Email, Channel, and Timestamp.

2.2 Unified Inbox (The Human Workspace)

Path: /dashboard/ai-assistant/inbox

Purpose: The central workspace where human agents claim and resolve tickets that the AI could not handle. This is the Human Conversation Hub.

The Human Takeover Workflow

Layout Structure: A robust 3-pane Support Desk layout designed to give the human total context rapidly.

• Left Pane: Conversation List

  • Tabs:
    • Unassigned: Escalated chats no agent has claimed yet. Displays a red numbered badge.
    • Mine: Chats currently locked to the logged-in agent.
    • Resolved: Past chats that were handed back to the AI or closed, kept for auditing.
  • Cards: Display Customer Name, Channel Icon (e.g., WhatsApp vs Widget), Last Message Preview, and a red dot for unread status.

• Middle Pane: Active Chat Thread (The Human Arena)

  • Header: Shows the customer name, channel, and a prominent "Resolve Chat" button. Clicking this tells the system the human is done and the AI should take over again.
  • Message Bubbles:
    • AI Messages: Shown in a distinct gray bubble with a 🤖 icon so the human knows what the bot said.
    • Customer Messages: Shown on the left in white/dark gray.
    • Agent Messages: Shown on the right in the primary brand color (e.g., Purple).
  • Composer Area (Security Lock): The chat input is strictly disabled and greyed out when the agent views an Unassigned ticket. They must click a large "Assign to Me & Take Over" button. This explicitly updates ChatSession.assignedAgentId in the database, preventing two agents from chatting with the same customer simultaneously. Once assigned, the text box unlocks.

• Right Pane: Context & User Profile

  • Details: Extracts attributes from the CustomerContact table (Email, Phone, First Seen, Location, Current Page URL).
  • AI Summary (The Lifesaver): A 2-sentence summary auto-generated by the LLM the exact moment the chat escalated. E.g., "Customer is frustrated about a double charge on March 12th. I could not verify billing." This means the human agent doesn't have to scroll up and read 50 previous messages to catch up.

2.3 Knowledge Base

Path: /dashboard/ai-assistant/knowledge

Purpose: Where the business owner trains the AI.

Tabs:

1. 🗂️ File Uploads
   • UI: A drag-and-drop zone accepting .pdf, .txt, and .docx.
   • List: A table beneath showing File Name, Upload Date, and Status (Processing... -> Trained 🟢).
2. 🌐 Web Scraper
   • UI: An input field: "Enter URL to scrape". A list of previously scraped pages.
   • Feature: A "Re-sync" button to tell the backend crawler to fetch the page again if pricing changed.
3. 💬 Q&A Rules (Manual Overrides)
   • UI: A simple form to input specific answers.
   • Use Case: If the AI consistently answers a question wrong, the owner can add a hard rule: Q: "Do you have an affiliate program?" A: "Yes, it pays 20%."

2.4 Settings & Persona

Path: /dashboard/ai-assistant/settings

Purpose: Configuring the behavioral personality of the LLM.

Sections:

1. Bot Identity Card:
   • Input: Bot Name (e.g., Sarah).
   • Input: Fallback Message (What the bot says exactly when it gives up: "Let me get a human...").
2. Deep Persona Editor:
   • UI: A large <textarea> where the owner explicitly defines instructions.
   • Helper Text: "Tell the bot how to act. E.g., 'Be extremely brief, use emojis, and always end by asking a question.'"
3. Advanced LLM Controls (Optional/Pro Tier):
   • Slider: Creativity / Temperature (0.0 to 1.0).
   • Dropdown: Model Selection (Fast & Cheap vs Smart & Slow).

2.5 Lead Capture Rules

Note: This might live inside Settings or as its own tab.

Path: /dashboard/ai-assistant/lead-capture

Purpose: Defining when the bot should gate information behind an email capture.

UI Interactions:

• Rule Builder Logic Flow:
  • IF user asks about: [Pricing Options ▼]
  • THEN bot must ask for: [Email Address ▼]
  • USING this prompt: [Input: "Before I share our pricing sheet, what's your best email address?"]
• Visuals: A list of active rules that can be toggled On/Off.

2.6 Channels (Integrations)

Path: /dashboard/ai-assistant/channels

Purpose: Activating the bot on public platforms.

UI Grid: A grid of identical cards for each channel.

1. Website Widget Card
   • Status: Active / Inactive toggle.
   • Action: Clicking "Configure" opens a modal showing a copyable <script> tag snippet.
   • Customization Form: Choose the widget brand color (hex code), positioning (bottom-left vs bottom-right), and welcome notification text.
2. WhatsApp Business API Card
   • Status: Requires Auth / Active.
   • Action: Clicking "Connect" opens an OAuth popup to Meta, or provides instructions on how to paste their Permanent Access Token and Phone Number ID securely into a vaulted password input.
3. Telegram (Coming Soon) Card
   • Displayed as deactivated/greyed out.

3. Empty States & Onboarding Experience

To ensure business owners don't feel overwhelmed, the system must employ a guided onboarding flow on their first visit to the AI Assistant module.

The Setup Wizard Flow:

1. Step 1: Name your Bot.
2. Step 2: Upload your first document (Provide an example menu/PDF).
3. Step 3: Try it out. (A sandbox chat interface embedded in the dashboard where the owner can test the bot before deploying it to a real channel).
4. Step 4: Launch. (Redirects to the Channels page to copy the website widget code).

2.7 Analytics & Insights

Path: /dashboard/ai-assistant/analytics

Purpose: Quantify the ROI of the AI Assistant so the business owner can justify the investment.

UI Components:

1. KPI Cards Row:
   • Total Conversations: Count of all ChatSession records in the selected period.
   • AI Resolution Rate: Percentage of sessions that never entered human_escalated. Higher is better.
   • Avg. Response Time: Mean latency between customer message and AI reply (target: <2s).
   • Leads Captured: Count of CustomerContact records created via leadCaptureRules.
2. Resolution Breakdown Chart:
   • Stacked bar chart: AI-Resolved vs. Human-Resolved vs. Abandoned, grouped by day.
3. Top Unanswered Questions:
   • A ranked table of questions that caused [[HANDOFF]]. Each row shows the question text, occurrence count, and a quick "Add to Knowledge Base" button that opens a modal pre-filled with the question.
4. Lead Funnel:
   • A funnel visualization: Page Visitors → Widget Opened → Message Sent → Email Captured → Demo Booked.
5. Token Usage & Cost:
   • A line chart showing daily accumulatedTokens spend with a projected monthly cost.

2.8 Sandbox / Test Chat

Path: /dashboard/ai-assistant/sandbox

Purpose: Let the business owner chat with their own AI in a safe, private environment before deploying it to customers. This is the single most important trust-building feature.

UI Components:

• Split View:
  • Left Panel: A real chat interface that mimics the Website Widget look and feel. The owner types messages and receives AI responses in real-time via SSE.
  • Right Panel (Debug View): Shows the raw prompt being constructed behind the scenes:
    • The <SYSTEM_INSTRUCTIONS> block.
    • Which RAG chunks were retrieved and their cosine similarity scores.
    • The token count breakdown (System: 400, History: 200, RAG: 350, Response: 120).
• Reset Button: Clears the sandbox session history for a fresh test.
• Feedback Loop: After each AI response, two small buttons: 👍 (Good Answer) / 👎 (Bad Answer). Clicking 👎 opens a form to add the correct answer directly to the Knowledge Base.

4. Responsive & Mobile Design Rules

The dashboard is primarily a desktop experience, but agents may need to respond to escalations from their phone.