​

siteGuide

​

​

🧠 Core Intelligence Features

• Natural Language Understanding (NLU)
  Conversational AI that comprehends plain language, technical terms, and layered inquiries.
• Live Context Awareness
  Interprets the current page’s content and adjusts responses accordingly.
• Multi-Intent Recognition
  Processes compound requests and multi-step inquiries within a single input.
• Smart, Search-Backed Responses
  Pulls relevant content from page text, FAQs, documents, or external APIs.

​

🧭 Co-Browsing Capabilities

• Smart Navigation & Scroll Control
  Automatically scrolls to relevant sections as the user asks questions.
• Real-Time Element Highlighting
  Visually emphasizes content sections during conversation for clarity and engagement.
• Persistent Page-to-Page Memory
  Session memory continues uninterrupted as the user browses across different pages.
• Voice-Controlled Navigation (Mobile Compatible)
  Allows users to control the experience completely hands-free via natural speech.
• Dynamic Journey Mapping
  Displays a visual trail of content accessed via the AI assistant.

​

🧬 Persistent Session Intelligence

• Multi-Day Session Memory
  Remembers previous interactions even if the user leaves and returns days later on the same device.
• Email-Linked Session Recall
  Users can tell the AI their email address to recover previous sessions on any device or browser.
• Cross-Device Continuity
  Resume where you left off from desktop to mobile (or vice versa) using secure email verification.
• Long-Term Context Retention
  Supports session recovery and memory for weeks or even months for returning users.

​

💬 User Interaction & Lead Capture

• Passive Lead Collection During Chat
  Gathers user info and contact details naturally during the flow of conversation.
• Auto-Populated Contact Forms
  Fills in website forms from user-provided information during the chat session.
• Pre-Submission Smart Routing
  Offers targeted help or staff escalation before the user finishes a question or submits a form.
• Segmented Inquiry Detection
  Categorizes questions (e.g. billing vs. tech support) and routes them appropriately.

​

🛠️ Platform Integration

• One-Click WordPress Plugin Deployment
  Easy install, even across multi-site environments.
• Powered by n8n Workflows
  Every interaction runs through fully customizable n8n automations on your backend.
• WebSocket Infrastructure for Real-Time Sync
  Real-time messaging persists through page loads, site navigation, and browser refreshes.
• CRM + Calendar Sync
  Connects directly to client CRMs and calendars to schedule meetings, save lead data, or create tasks.

​

🎨 Customization & Brand Control

• Custom Persona & Language
  Fully customizable tone of voice, vocabulary, and branded phrasing.
• Text + Voice Interface
  Users can type or speak freely and seamlessly switch between modes.
• Style Controls
  Modify the bubble appearance, position, assistant avatar, and animation behaviors.
• Page-Specific Intelligence
  Tailor assistant behavior and prompt logic to different URLs or sections of the site.

​

📊 Analytics & Optimization

• Real-Time Dashboard
  View user engagement stats, conversion triggers, and performance data.
• Conversation Review + Playback
  Replay anonymized chat logs to refine training and detect missed opportunities.
• A/B Testing for Copy & UX
  Test different versions of the assistant’s greeting, responses, and behavior logic.
• Lead Attribution Tracking
  Tracks where leads came from and what pages or phrases triggered their inquiry.

​

🔐 Security & Control

• Bot Detection Before Submission
  Identifies spam bots or automated tools before they reach the contact form.
• End-to-End Session Security
  Sessions linked by email are encrypted and validated securely.
• Privacy-First Design
  Complies with GDPR, CCPA, and other major privacy standards out of the box.
• Live Agent Override
  Human team members can jump in and take over at any point via internal alerts.

​

🔌 1. Infrastructure & Hosting

• WebSocket Server (Real-time bidirectional comms)
  • Self-hosted (DigitalOcean / VPS): ~$12–$40/month per instance
  • Managed (e.g. Pusher, Ably, or Socket.io cloud): ~$49–$199/month depending on connection limits and message volume
• Static Hosting for Plugin Assets (JS/CSS bundles)
  • Typically negligible if included in WordPress plugin or bundled with your site
  • ~$0 if served via WordPress CDN or your own cloud
• SSL & Domain Setup
  • Included in most cloud providers or ~$5–10/month if separately hosted

​

🧠 2. AI-Powered Page Analysis & Navigation Control

• DOM Parsing & Element Mapping Scripts
  • One-time development cost to extract meaningful content blocks
  • Ongoing cost: minimal unless AI is being used to interpret every page on load
• Client-Side Highlighting/Scrolling Logic
  • One-time front-end development expense
  • Open-source libraries like scroll-into-view, IntersectionObserver, and MutationObserver are free

​

🗂️ 3. Session Persistence Across Visits

• LocalStorage/IndexedDB (on device)
  • Free, used for same-device memory
  • Stores session token or context ID
• Server-Side Session Storage (cross-device)
  • Redis, PostgreSQL, or Firestore:
    • ~$5–$30/month for storing session IDs, page history, and user metadata
• Email-Linked Context Recovery
  • Secure database lookup + encryption
  • Very lightweight unless storing extensive conversation history

​

🔧 4. Maintenance & Scaling

• Error Monitoring / Logging (optional but recommended)
  • Sentry or LogRocket: Free tier or ~$20/month
• Traffic Scaling (if co-browsing is used by thousands simultaneously)
  • May require load balancing or multiple instances of WebSocket servers
  • Scale cost = ~$20/month per 10k concurrent users (estimate, varies heavily)

​

💡 Estimated Monthly Overhead for Co-Browsing Features

• Get lost or frustrated
• Abandon their inquiry before reaching the right page
• Never complete the form or call

1. Conversational Interface
   Users interact with the AI using natural language — typing or speaking — just like they would with ChatGPT or Siri.
2. Real-Time Website Control
   When a user asks something like, “What are your pricing options?” or “Where’s the warranty info?” the AI will not only answer, but automatically scroll to the relevant section, highlight it, and guide the user’s attention there.
3. Cross-Page Memory
   The assistant keeps track of what’s been discussed even as the user navigates between different pages.
4. Session Persistence
   If a user leaves the site and comes back days or weeks later — they can pick up right where they left off. Even if they’re on a different device, they can tell the AI their email address and resume their previous session.
5. Lead Capture
   As the conversation unfolds, SiteGuide naturally collects user information — name, email, questions — without feeling intrusive. It fills out forms for them, routes inquiries to the right department, and can even book appointments via integration with calendars and CRMs.
6. Voice + Mobile Support
   On mobile, users can speak to the assistant hands-free, making this ideal for on-the-go interactions.

• Frontend (Website Plugin): A lightweight WordPress plugin injects SiteGuide onto any website. This script manages the UI, handles user interactions, and displays the assistant in a friendly chat-style interface.
• Backend (DigitalOcean Server): The real-time communication and logic are powered by a custom backend running on DigitalOcean. It includes a WebSocket server for persistent two-way communication.
• Automation Engine (n8n): All interactions are processed through n8n workflows — a no-code automation engine — allowing SiteGuide to be deeply customized for each business (e.g., different responses for different pages or industries).
• Data Layer (Supabase): Session memory, user history, and conversation context are stored securely in Supabase — a modern backend-as-a-service platform that offers real-time sync, authentication, and PostgreSQL storage.

• For Users:
  SiteGuide transforms the browsing experience into something active and human. It lowers friction, increases satisfaction, and helps users reach what they want faster.
• For Businesses:
  It dramatically improves lead generation, conversion rates, and support efficiency — without requiring live staff. Every interaction is logged, measured, and repeatable. It’s like giving every website visitor their own intelligent assistant.
• For Agencies & SaaS:
  This is deployable at scale. One plugin. One backend. Thousands of clients — each with their own AI, workflow logic, and memory.

• A monthly subscription per site (e.g., $19–$97/month)
• Or bundled into higher-tier web service packages
• With optional per-session or per-lead pricing for larger enterprise clients

​

🚀 Zero-Friction Deployment: Instant Compatibility with WordPress

• No developer required
  Any business owner or agency can deploy the AI assistant in seconds, without writing a single line of code.
• Instant Compatibility with 43% of the Internet
  WordPress powers over 43% of all websites worldwide. By starting here, SiteGuide gains access to a massive install base without needing enterprise partnerships or long sales cycles.
• Built-in Plugin Infrastructure
  With updates, support, and configuration handled inside the WordPress admin dashboard, it behaves like any other premium plugin — seamless, familiar, and manageable.

​

🔄 Scalable to Any Website

• Shopify
  As a storefront assistant with product navigation, cart reminders, and support built in.
• Webflow, Wix, Squarespace
  For solopreneurs, artists, and small businesses that need frictionless onboarding.
• Custom-built platforms
  By offering a drop-in JavaScript snippet (like Google Analytics or Drift), SiteGuide can run on any website — even enterprise portals and SPAs.

​

🔥 CORE FEATURES

1. Conversational AI Interface
   Natural language interaction through voice or text, enabling users to ask questions or give commands.
   Priority: High
2. Smart Scroll & Element Highlighting
   AI scrolls the page and highlights relevant content in real time, drawing user attention to specific sections.
   Priority: High
3. Cross-Page Memory
   Maintains the user’s conversation and context as they navigate across different pages of the site.
   Priority: High
4. Persistent Sessions
   Saves user sessions to allow them to return days or weeks later and resume where they left off — even across devices using email-linked recovery.
   Priority: High
5. Real-Time Lead Capture
   Seamlessly collects user data during natural conversation without relying on traditional form submissions.
   Priority: High
6. Voice-Controlled Navigation
   Users can navigate the site hands-free using spoken commands, ideal for mobile users.
   Priority: Medium
7. Page-Aware Behavior
   AI customizes its tone, responses, and actions based on the type of page the user is on (e.g., pricing, blog, checkout).
   Priority: Medium

​

🧭 CO-BROWSING & INTERACTION LAYERS

8. Visual Pointer Overlay
   The AI uses subtle visual cues (arrows, pulses, highlights) to direct the user’s attention during guidance.
   Priority: Medium
9. Dynamic Journey Map
   Shows a breadcrumb or visual timeline of where the user has been guided, allowing quick backtracking.
   Priority: Low
10. Agent Shadow Mode
    Lets a team member silently view what the user is doing in real time and optionally take over if needed.
    Priority: Medium
11. AI-to-Human Handoff with Context Transfer
    Enables seamless escalation to a human rep, with the full chat log and navigation trail handed over.
    Priority: Medium
12. Live Element Tracking (Scroll Sync + DOM Awareness)
    Ensures the AI always understands the structure of the current page and tracks active user sections.
    Priority: High

​

🔧 PLATFORM INTEGRATION & AUTOMATION

13. Instant WordPress Plugin Deployment
    Easily install SiteGuide on any WordPress site with a plugin — no code required.
    Priority: High
14. Supabase-Powered Session Storage
    Securely stores and retrieves session data using Supabase for long-term, cross-device memory.
    Priority: High
15. n8n Workflow Engine Integration
    Every user interaction flows through n8n automations, allowing full customization per site.
    Priority: High

​

🧾 SiteGuide with Co-Browsing

​

📌 1. Overview

​

1.1 Product Summary

​

1.2 Core Objective

​

🎯 2. Core Features & Functional Requirements

​

2.1 Conversational AI Interface

• Chat bubble visible on all site pages (unless suppressed by admin settings)
• Opens into a floating modal with:
  • Input field (text)
  • Microphone icon (voice)
  • AI response pane with smooth message rendering
• Widget must be draggable and mobile-responsive

• Understands conversational questions (e.g., “What’s your refund policy?”)
• Can reference current page context and DOM content
• Pulls FAQs, structured page data, and metadata for its responses
• Allows seamless switching between text and voice

• AI inference handled via OpenAI, Claude, or other LLM APIs
• Memory and conversation history stored in Supabase, tied to session token
• Voice processed via Web Speech API (MVP) or ElevenLabs (enhanced)

​

2.2 Scroll-to-Element & Highlighting

• DOM is scanned on page load using custom JavaScript to identify common blocks: headers, pricing tables, FAQs, images, etc.
• Scroll to the relevant element using scrollIntoView({ behavior: 'smooth' })
• Apply temporary CSS highlighting animation (glow, border pulse)

• box-shadow pulse on container div
• Border color shift for attention
• Optional pointer icon (Phase 2)

• Use semantic tags, data-siteguide attributes, or nearest heading anchors
• Classify content using tag weight (e.g., <h2> over <p>)
• Use XPath or document structure for fallback targeting

​

2.3 Persistent Session Memory

• Session ID generated and stored in localStorage
• All interactions logged in Supabase under session ID
• Memory includes chat, page visits, scrolls, highlights, lead data

• At any point, user can say “Remember me” or give their email
• Session ID linked to email in Supabase
• On future visits (even new devices), user can say “Pick up where I left off” or input email to resume

• Session TTL: 6 months minimum
• All context is loaded and rehydrated into frontend memory store on reconnect
• Expired sessions are archived but queryable for analytics

​

2.4 Multi-Page Context Tracking

• Each page change updates currentPage and referrerPage in memory
• Supabase logs:
  • session_id
  • page_url
  • timestamp
  • scroll_position
  • interaction_type

• If a user asks about a feature they saw earlier, AI should be able to say:
  “You were looking at the pricing page earlier. Would you like me to take you back?”

​

2.5 Lead Capture via Conversation

• Name (inferred from question: “Hi, I’m Sam — I had a question about pricing.”)
• Email (“You can send it to sam@email.com”)
• Phone number (if mentioned)
• Type of inquiry (detected from conversation content)

• Data auto-injected into any active form on the page (via JavaScript)
• Optionally pushed to Supabase or n8n workflow for CRM sync

• Webhook or Supabase trigger sends lead to connected CRM (e.g., HubSpot, Salesforce)
• Triggers follow-up automation

​

2.6 WordPress Plugin Delivery

• Easy upload and install via .zip or WordPress marketplace
• Plugin admin panel includes:
  • AI assistant name and welcome message
  • Toggle for voice mode
  • Page exclusion rules
  • Widget placement settings (bottom right, left, inline, etc.)
• Plugin auto-loads core script across public pages

• Asynchronous script load
• Degrades gracefully if disabled
• Securely connects to WebSocket backend

​

2.7 Voice Interaction (MVP + Enhanced)

• Microphone toggle on widget
• Press-to-talk or voice wakeup (MVP: manual only)

• AI responds using browser TTS or ElevenLabs API
• Should reflect tone: cheerful, helpful, confident, etc.

• Voice must fallback to text if browser lacks microphone
• All spoken output must also appear as text

​

2.8 WebSocket Real-Time Sync

• AI sends scroll or highlight commands in real-time
• AI receives live context updates (user location, clicks, etc.)

• Socket ID assigned per session
• Keep-alive with heartbeat every 15s
• Reconnect with exponential backoff

• Socket.io or WS (Node.js)
• Host on DigitalOcean server with TLS and rate limits

​

2.9 Supabase Storage Architecture

• users →
• sessions →
• interactions →
• page_visits →
• leads →

• Use Supabase RLS (Row-Level Security)
• Read/write access only for authenticated backend

​

2.10 Admin/Agent Shadow Mode (Phase 2)

• View active session list in dashboard
• Click into a session to view current page and scroll state
• Option to “ghost” the user without intervention

• Streaming scroll position via WebSocket
• Read-only DOM mirror (sanitized)

​

🧪 3. Success Criteria (MVP)

​

✅ What’s Already Excellent

​

🧠 Conceptual Clarity

• The product’s purpose, goals, and unique value are clearly defined.
• Differentiation from competitors is well understood and implementation-focused.

​

🔧 Functional Coverage

• Features are broken down with detailed behavioral expectations.
• Technical systems like WebSockets, Supabase schema, and session logic are outlined clearly.
• Integration points (n8n, WordPress, Supabase) are mapped.

​

🧪 Success Metrics

• Each feature includes a measurable performance benchmark, which guides QA and iteration.

​

🔍 What’s Still Needed for Development Readiness

​

1. UX/UI Specifications (Missing)

• Full wireframes or UI mockups for:
  • Assistant interface (desktop and mobile)
  • Plugin admin panel in WordPress
  • Lead capture confirmation state
• Interaction design (e.g., animations for scroll/highlight, voice input UI behavior)

​

2. LLM Prompt Engineering Guidance

• Prompt templates for:
  • Initial greeting
  • Memory-aware follow-ups
  • Scroll-to commands (“scroll to the pricing section”)
  • Highlight decisions
• Fallback behavior if no matching element is found

​

3. Data Flow Diagrams / Sequence Charts

• Sequence diagram for:
  • Session creation → interaction → session recall
  • Scroll/highlight command flow (AI → backend → frontend)
  • Lead capture and dispatch via n8n

​

4. Testing Plan & Edge Cases

• What to test and how:
  • Session recovery across incognito vs. logged-in devices
  • How the AI handles failed scroll/highlight attempts
  • How voice behaves on unsupported browsers
  • Race conditions with fast page switching

​

5. CI/CD + Deployment Environment Plan

• Where the plugin JS is hosted (CDN?)
• Deployment structure for the WebSocket server (Docker? PM2? Horizontal scaling?)
• Versioning and rollback strategy
• Staging vs. production environment separation

​

🟢 Final Verdict

• This PRD is 80–85% complete
  It gives me the why, what, and how of the system.
• To ship with confidence, I’d need:
  • Visual mockups / UX spec
  • Prompt templates for LLM behavior
  • Architecture and event flow diagrams
  • Deployment and testing details

​

🧾 PRD Outline for SiteGuide with Co-Browsing

​

1. 📌 Introduction

​

1.1 What is SiteGuide?

​

1.2 Core Value Proposition

​

1.3 Deployment Targets

​

2. 🎯 Product Goals

​

2.1 Primary Goals

• Real-time AI-powered navigation
• Automatic scrolling and content highlighting
• Persistent sessions across visits/devices
• Lead capture during conversation

​

2.2 Success Criteria

​

3. 🧠 Feature Overview

​

3.1 Summary Table

• Title
• Description
• Inputs/outputs
• Priority

​

4. 🧱 System Architecture

​

4.1 High-Level Diagram

​

4.2 Data Flow Maps

• Page load → chat open → AI response → scroll
• Session creation → memory store → recall via email
• Lead captured → send to CRM

​

5. ⚙️ Technical Components (Modular Breakdown)

​

5.1 Frontend Widget

• Chat UI (text & voice)
• Scroll and highlight logic
• DOM observer
• Local session storage
• Voice interaction handler

​

5.2 WordPress Plugin

• Script injector
• Admin panel (branding, placement, toggles)
• Page-level control

​

5.3 WebSocket Server

• Persistent connection
• Message routing (scroll/highlight/data)
• Authentication (anon or email-linked)

​

5.4 Supabase

• Data schema
• Row-level security
• Realtime listeners

​

5.5 LLM Logic Layer

• Prompt templates
• Context embedding
• Response validation
• Fallback handling

​

5.6 n8n Integration

• Lead push (to CRM, email, etc.)
• Session activity logging
• Trigger-based automations

​

6. 🛠️ Feature Specifications (One-by-One)

• Title
• User Story
• Functional Requirements
• Edge Cases
• Frontend Behavior
• Backend Logic
• Storage Requirements
• Success Criteria
• Dependencies

• AI conversation engine
• Scroll-to-element
• DOM highlighting
• Visual pointer
• Voice commands (STT and TTS)
• Email-linked session recall
• Multi-page session memory
• Lead capture
• Plugin install experience
• Mobile and desktop behavior
• Real-time communication via WebSocket
• Offline/degraded mode behavior

​

7. 🧪 Testing & QA Plan

​

7.1 Unit Tests

​

7.2 Integration Tests

​

7.3 Manual QA Flows

​

8. 🎨 UI/UX Specifications

​

8.1 Widget Wireframes

​

8.2 Highlight/Pointer Animations

​

8.3 Plugin Admin Panel Mockups

​

9. 🔐 Security & Privacy

​

9.1 Data Collection Rules

​

9.2 Storage Security

​

10. 🚀 Deployment Plan

​

10.1 Environments

​

10.2 Hosting

​

10.3 CI/CD

​

11. 🧰 Developer Resources

​

11.1 LLM Prompt Library

​

11.2 DOM Element Targeting Guide

​

11.3 WebSocket Message Formats

​

11.4 Supabase Schema & ERD

​

11.5 API Documentation

​

12. 📎 Appendices

• Glossary of Terms
• Fallback UI Modes
• Integration FAQs
• Support Ticket Handling (post-launch)

​

SiteGuide with Co-Browsing

​

1. Introduction

​

1.1 Product Summary

​

1.2 Problem Statement

​

1.3 Target Users

​

1.4 Use Cases and Scenarios

​

1.5 Goals and Non-Goals

​

2. Product Objectives and Success Criteria

​

2.1 Primary Objectives

​

2.2 Key Performance Indicators (KPIs)

​

2.3 Constraints and Assumptions

​

3. System Overview

​

3.1 Component Architecture

​

3.2 Data Flow and Lifecycle

​

3.3 High-Level Diagrams

​

3.4 Technologies and Tools Used

​

4. Functional Feature List

• Feature Name
• Description
• Dependencies
• Priority (Must, Should, Could)

​

5. Module Specifications

• Purpose
• Trigger/Event
• Inputs
• Outputs
• Behavior and Flow
• UI Requirements
• State Management
• Error Handling
• API Integration (if any)
• Storage or Persistence
• Edge Cases

​

5.1 Conversational Interface

​

5.2 Scroll-to-Element Functionality

​

5.3 DOM Highlighting

​

5.4 Visual Pointer (Optional)

​

5.5 Voice Input and Output

​

5.6 Session Persistence and Memory

​

5.7 Email-Linked Session Recovery

​

5.8 Cross-Page Memory Management

​

5.9 Lead Capture via Conversation

​

5.10 WordPress Plugin Delivery

​

5.11 WebSocket Connection Management

​

5.12 Supabase Integration for Storage

​

5.13 n8n Integration for Automation

​

5.14 Mobile-Responsive and Accessibility Behavior

​

5.15 Admin Shadow Mode (Optional, Phase 2)

​

6. Data and Schema Definitions

​

6.1 Supabase Table Schema

​

6.2 Entity Relationship Diagrams (ERD)

​

6.3 WebSocket Message Structure

​

6.4 LocalStorage and SessionStorage Structure

​

6.5 n8n Webhook Structures

​

7. UI/UX Specifications

​

7.1 Chat Widget Behavior and States

​

7.2 Voice Interface UX

​

7.3 Scroll and Highlight Animations

​

7.4 Assistant Avatar and Branding Options

​

7.5 Admin Panel UI (for WordPress Plugin)

​

8. Prompt Design and AI Behavior

​

8.1 Base Prompt Templates

​

8.2 Dynamic Prompt Variables

​

8.3 Page-Aware Prompt Adjustments

​

8.4 Fallback and Safety Logic

​

8.5 User Input Classification and Routing

​

9. Testing and Quality Assurance

​

9.1 Unit Test Requirements

​

9.2 Integration Test Plans

​

9.3 Manual QA Checklist

​

9.4 Regression Testing

​

9.5 Voice/Accessibility Testing

​

10. Deployment Plan

​

10.1 Hosting Requirements

​

10.2 Deployment Pipelines

​

10.3 Plugin Distribution and Versioning

​

10.4 CI/CD Strategy

​

10.5 Error Logging and Monitoring

​

11. Security and Compliance

​

11.1 Session Security

​

11.2 Supabase Row-Level Security

​

11.3 GDPR/CCPA Compliance

​

11.4 Voice and Data Consent

​

11.5 API Rate Limiting and Abuse Handling

​

12. Developer Tools and Support Materials

​

12.1 API and WebSocket Documentation

​

12.2 DOM Targeting Strategy and Examples

​

12.3 Local Dev Setup Guide

​

12.4 Sample Prompt Library

​

12.5 Troubleshooting and Debugging Guide

​

13. Appendix

​

13.1 Glossary of Terms

​

13.2 Browser Support Matrix

​

13.3 Phase 2 and Phase 3 Feature Planning

​

13.4 References and External Docs

​

1. Introduction

​

1.1 Product Summary

​

1.2 Problem Statement

• User familiarity with site layout
• Traditional form submissions
• Human intervention for sales or support
• Session loss upon reloads, navigation, or future visits

​

1.3 Target Users

• Small-to-medium businesses using WordPress or custom websites
• Marketing teams looking to improve engagement and lead capture
• Agencies who want to deploy a smart assistant across multiple client sites

• First-time visitors seeking fast answers
• Mobile users who prefer voice or hands-free interaction
• Users evaluating services (e.g., legal, health, B2B, education, etc.)

​

1.4 Use Cases and Scenarios

1. New Visitor Asking a Common Question
   “Where is your pricing?”
   → SiteGuide scrolls to the pricing section, highlights it, and explains key points.
2. Returning Visitor
   “Pick up where we left off.”
   → SiteGuide recalls the previous session, brings the user to the last page viewed, and reminds them of the conversation.
3. Mobile User with Voice Only
   “Can I schedule a consultation?”
   → SiteGuide responds audibly and begins the appointment booking process.
4. Lead Generation Without a Form
   As the user asks questions, SiteGuide captures name, email, and interest, then syncs it with the business CRM in the background.

​

1.5 Goals and Non-Goals

• Create a real-time, AI-driven assistant that can:
  • Answer questions contextually
  • Control website scroll and highlight functions
  • Persist user sessions over time and across devices
  • Work on mobile and desktop with voice input
  • Seamlessly capture leads during conversation
• Deliver via a lightweight WordPress plugin with zero developer setup required

• SiteGuide is not a human-agent chat platform (e.g., Intercom or Zendesk)
• It does not offer live screen-sharing or video calling
• It is not designed to provide support for complex account management or troubleshooting workflows
• It does not require, and should not rely on, external APIs for static site structure parsing

​

2. Product Objectives and Success Criteria

​

2.1 Primary Objectives

1. Enable real-time AI-guided browsing
   Users must be able to ask a question or express a need in natural language, and the assistant must:
   • Understand the request
   • Determine the relevant content on the page
   • Automatically scroll to and highlight that content
2. Capture lead information conversationally
   Without requiring a formal form submission, SiteGuide must detect and extract contact details (name, email, phone, intent) during natural dialogue and send them to the backend or CRM.
3. Support persistent session memory across time and devices
   The assistant must remember what a user saw, asked, or did in past visits, and allow:
   • Session recall via the same device (local ID)
   • Session recovery via email (cross-device)
4. Voice interaction for hands-free control
   On mobile and desktop browsers that support it, the assistant must allow:
   • Voice input (speech-to-text)
   • Voice output (text-to-speech)
   • Seamless toggling between voice and text modes
5. Deploy via WordPress plugin with no developer setup
   The entire co-browsing system must function as a plug-and-play solution. WordPress site owners must be able to:
   • Install the plugin
   • Customize its behavior through a visual admin interface
   • Activate it without writing or modifying any code
6. Real-time AI control via WebSocket
   Actions like scrolling and highlighting must be triggered instantly via two-way communication between the LLM backend and the browser widget. WebSocket architecture must support:
   • Persistent connections
   • Low latency (<200ms)
   • Session reconnection across page reloads
7. Front-end behavior must be fast and intuitive
   The assistant must not delay page load, interfere with page behavior, or create user frustration due to visual lag, misfires, or conflicting styles.

​

2.2 Key Performance Indicators (KPIs)

​

2.3 Constraints and Assumptions

• SiteGuide must not rely on modifying the structure of client websites (i.e., works with unknown HTML structures)
• LLM processing and WebSocket backend are hosted centrally and must serve many sites
• Not all devices or browsers will support voice interaction
• The assistant must work across both SPA (Single Page Application) and MPA (Multi-Page Application) WordPress themes

• Most users will not have JavaScript or cookies disabled
• Most deployments will be on modern WordPress websites using themes that follow semantic HTML practices
• Businesses using SiteGuide will prefer ease of use over customization
• Internet connectivity is stable enough to support persistent WebSocket communication

​

3. System Overview

​

3.1 Component Architecture

​

1. Client-Side Widget (Frontend)

• The user interface (chat, voice, and assistant behavior)
• Page manipulation (scrolling, highlighting, pointer rendering)
• Real-time communication with the backend over WebSocket
• DOM scanning and target matching
• Local memory and session management

​

2. WordPress Plugin

• Installs and injects the SiteGuide widget on all site pages
• Provides a GUI admin panel for customization (e.g., assistant name, color, visibility rules)
• Connects to the aiConnected backend via provided credentials

​

3. WebSocket Server

• Bridges real-time communication between the assistant frontend and the AI backend
• Receives structured commands from the LLM (e.g., “scroll to pricing”) and emits them to the appropriate client
• Maintains socket sessions per user/site
• Supports multi-tenant infrastructure (each WordPress site = a tenant)

​

4. LLM Processing Layer

• Interpreting user inputs (voice or text)
• Generating context-aware responses based on website structure, session memory, and intent
• Producing structured action instructions (e.g., {action: "scroll", target: "faq_section"})

​

5. Supabase (Database and Session Memory)

• Session persistence (page visits, conversation logs, memory embeddings)
• Lead storage (name, email, message intent)
• Cross-device session recall via user ID/email
• Real-time row-based syncing (optional)

​

6. n8n Workflow Automation

• Sending captured leads to CRM or email
• Triggering internal alerts or follow-ups
• Logging analytic events (e.g., session started, session resumed, form auto-filled)

​

3.2 Data Flow and Lifecycle

​

Basic Lifecycle: Anonymous User

1. Page loads → widget initializes → anonymous session ID created
2. User opens assistant → begins chat or voice interaction
3. Input sent to AI via WebSocket → AI interprets + responds
4. AI sends structured action (e.g., scroll, highlight) to frontend
5. Actions are executed and logged (conversation, actions, DOM references)
6. User may provide an email → anonymous session is upgraded to persistent session

​

Returning User (Same Device)

1. Widget checks for siteguide_session_id in localStorage
2. If found, fetches memory from Supabase
3. Assistant greets the user and optionally offers to resume last session

​

Returning User (Different Device)

1. User says “Pick up where I left off” or provides email
2. Widget makes authenticated query to Supabase to fetch session history
3. Memory is restored and interaction resumes

​

3.3 High-Level Diagrams

• Component Communication Flow (Frontend → WebSocket → AI → Supabase)
• Session Lifecycle Diagram
• DOM Interaction Flow (scroll → highlight → pointer → confirmation)
• Multi-tenant architecture for scaling across many websites

​

3.4 Technologies and Tools Used

​

4. Functional Feature List

​

Feature Priority Key

• Must: Required for MVP launch. These features must be stable, tested, and integrated.
• Should: Not strictly required for MVP but highly recommended for product completeness or reliability.
• Could: Nice-to-have or experimental features that can be deferred or gated behind admin controls.

​

5.1 Conversational AI Interface

​

Purpose

​

User Story

• As a visitor to a website, I want to ask questions in a natural way so that the AI can help me find the content I need without searching manually.
• As a mobile user, I want to speak to the assistant and receive spoken answers hands-free.
• As a returning visitor, I want the assistant to remember me and pick up where I left off.

​

Functional Requirements

​

Input Handling

• Accepts natural language input from user via text field.
• Optional microphone button allows speech-to-text input via Web Speech API.
• Detects when input is empty, too short, or outside expected behavior (e.g., non-verbal sounds).
• Detects user requests that are:
  • Content-related (e.g., “Where is the pricing?”)
  • Procedural (e.g., “I want to schedule a consultation.”)
  • Memory-linked (e.g., “Pick up where I left off.”)
  • Identifying (e.g., “My email is john@acme.com.”)

​

AI Query Execution

• Formats user input into a structured JSON payload:

{
  "session_id": "abc123",
  "message": "Where is the pricing?",
  "page_url": "https://clientsite.com/pricing",
  "timestamp": 1692721934,
  "device_info": {...},
  "memory_context": {...}
}

• Sends query to backend AI processor via WebSocket or REST (depending on architecture decision).
• Waits for AI response or fails after a defined timeout (e.g., 10 seconds).
• On error, shows fallback response:
  “I didn’t quite catch that. Can you try rephrasing it?”

​

Output Rendering

• Renders AI response in chat bubble using typing animation (e.g., one character per 10ms).
• Response may include:
  • Plain text
  • Action instructions (e.g., scrollTo, highlight, captureLead)
  • Follow-up question prompts (e.g., “Would you like me to show you that section?”)

​

Session Interaction

• Saves every message (user and AI) to session memory in Supabase, with timestamp and message type.
• Tracks which messages triggered downstream actions.
• Supports follow-up chaining: AI can ask for clarification or present follow-up options.

​

Voice Output

• If voice mode is enabled, the AI’s response is also read aloud using:
  • Web Speech API (MVP)
  • ElevenLabs TTS (optional Phase 2)
• Auto-disables if browser lacks TTS capability.

​

Trigger Events

​

UI/UX Requirements

• Chat bubble is persistent in lower right corner of screen (customizable).
• When clicked, opens a full chat window with:
  • Assistant avatar
  • Conversation thread (persisted across pages)
  • Input field
  • Optional microphone toggle
• Supports mobile layout:
  • Full-screen modal on phones
  • Larger tap targets
  • Voice interaction primary, with fallback to text

​

State Management

• Local session state is stored in memory using JavaScript module or context provider:

const session = {
  id: "abc123",
  messages: [...],
  lastPage: "/pricing",
  memoryTokens: [...],
  voiceEnabled: true,
};

• On every input or response, session is synced with Supabase (async).

​

Error Handling

• If voice input fails (e.g., user denies microphone access), show:
  “It looks like I couldn’t access your microphone. Try typing instead.”
• If AI times out, show:
  “I’m having trouble connecting to the assistant right now. Please try again in a moment.”
• If AI response is missing expected structure, fallback to:
  “Here’s what I found—but I couldn’t navigate for you just yet.”

​

API Integration

• AI backend endpoint:
  POST /ai/interpret (or WebSocket message channel)
  Expected response:

{
  "message": "The pricing section is just below.",
  "action": "scroll",
  "target": "#pricing-table",
  "memory": {...},
  "suggestedFollowUp": "Would you like to compare plans?"
}

• Supabase:
  • insert into conversations table
  • upsert session memory
  • Optional trigger to n8n for sentiment or analytics

​

Storage Requirements

• All messages (user and AI) stored in Supabase with:
  • session_id
  • sender_type (user/ai)
  • message_text
  • timestamp
  • page_context
  • action_triggered (boolean)

​

Edge Cases

• User gives empty input: disable send button
• User speaks but says nothing (e.g., background noise): discard event
• Multiple users on same device/browser: store separate sessions with unique anonymous IDs
• Connection drops during interaction: queue message locally, retry once WebSocket reconnects

​

Success Criteria

• ≥ 90% of valid inputs receive AI responses within 2 seconds
• 100% of sessions have messages logged in Supabase
• Typing, response, and scroll behavior feel natural and humanlike
• Voice mode works on ≥ 80% of supported mobile devices
• Assistant resumes previous session on page reload or site revisit without user confusion

​

5.2 Scroll-to-Element Functionality

​

Purpose

​

User Story

• As a site visitor, when I ask a question like “Where is your refund policy?” I want the assistant to automatically scroll the page to that section instead of just telling me to scroll manually.
• As a business owner, I want the assistant to physically guide users to the correct areas of the page so users spend less time searching and are more likely to engage.

​

Functional Requirements

​

AI Response Instruction

• The assistant must receive from the AI backend a scroll instruction that includes:
  • action: "scroll"
  • target: "<DOM selector>" (e.g., #pricing-table, .faq-item-3)
• If no valid scroll target is returned, the assistant must fall back to a text-only response (see error handling).

​

DOM Scanning (Frontend)

• On page load (or after DOM mutations), SiteGuide must scan and cache all scrollable targets.
• Each section should be indexed based on:
  • Semantic tags (section, article, main, aside)
  • Headings (h1–h4)
  • Attributes (data-siteguide-target, id, class)
• A “target map” should be built in memory:

{
  "#pricing-table": HTMLElement,
  ".faq-section": HTMLElement,
  "h2:contains('Our Process')": HTMLElement
}

​

Scroll Behavior

• The scroll command must:
  • Smoothly scroll the user’s browser viewport to the element
  • Use scrollIntoView({ behavior: 'smooth', block: 'start' })
  • Offset for fixed headers (e.g., subtract 80px if a sticky nav is detected)
• Only scroll if the target element exists and is visible in the DOM
• If user scrolls away during AI animation, the assistant should:
  • Respect user override (no forced re-scrolling)
  • Optionally offer to “Take me back” with a button

​

Scroll Trigger Lifecycle

• Receive scroll instruction via WebSocket message or structured response
• Look up target in local target map
• Validate that it’s a scrollable element (not display: none, visibility: hidden, or detached from DOM)
• Execute scroll animation
• Trigger internal log:

logScrollEvent({
  session_id,
  target_selector: "#faq-section",
  timestamp: Date.now(),
  autoTriggered: true
});

​

Trigger Events

​

UI/UX Behavior

• If a scroll is triggered by the AI, the assistant chat should say:
  • “Let me show you…” or “Here’s what you’re looking for.”
• After the scroll, the highlighted element should remain on screen (see 5.3)
• Optional: show a floating “Back to chat” button if scroll takes user far away from assistant position

​

State Management

• Current scroll target should be stored in memory for:
  • Restoring scroll position later
  • Analytics
  • Displaying “recently visited” interactions

state.lastScrollTarget = "#refund-policy";

​

Error Handling

​

API/AI Format (Expected)

{
  "message": "The pricing information is in the section below.",
  "action": "scroll",
  "target": "#pricing-table"
}

​

DOM Targeting Best Practices

<section id="pricing-table" data-siteguide="pricing">...</section>

​

Success Criteria

• ≥ 90% of valid scroll actions land on the correct content section
• Scroll animation duration is ≤ 600ms and feels natural
• Element is visible in the viewport after scrolling
• No jitter, double-scrolling, or abrupt jumps
• Scroll does not interfere with core page functions (e.g., modals, nav bars)

​

Where it fits in the PRD

• Programmatically click buttons or links
• Navigate to new internal pages without losing session memory
• Resume chat context immediately upon load

​

Why it matters

• Clicking “Book Now” for the user
• Jumping from homepage to pricing
• Taking the user to “Contact” or “Testimonials” pages when asked

​

Technical Implications

• Intercept link clicks triggered by SiteGuide (not the user)
• Store all session data and conversation history in local memory (and Supabase)
• Rehydrate the assistant UI instantly after page reload
• Maintain the open chat state, scroll history, and conversation log

​

5.3 DOM Element Highlighting

​

Purpose

​

User Story

• As a user, when the assistant scrolls me to a section, I want to instantly understand which part is relevant so I don’t waste time guessing.
• As a business owner, I want the assistant to visually call out key information like pricing, guarantees, or lead forms to maximize conversion.

​

Functional Requirements

​

Trigger Conditions

• Highlighting is activated after a successful scroll event.
• May also be triggered independently if the AI refers to a visual element (e.g., “Look at the refund section above.”).

​

Target Identification

• Same target selector is used as for scrolling (e.g., #faq-section, .refund-policy)
• If no valid target is available, assistant should skip highlighting

​

Visual Behavior

• Highlight effect is non-obtrusive, WCAG-compliant, and disappears after a short duration (configurable)
• Acceptable effects:
  • Pulse border: animated outline glow around element
  • Background fade: gentle highlight color behind content
  • Animated outline: CSS box-shadow flicker or ring animation

.siteguide-highlight {
  outline: 3px solid #facc15;
  outline-offset: 4px;
  animation: pulseHighlight 1.5s ease-in-out 2;
}
@keyframes pulseHighlight {
  0% { outline-color: transparent; }
  50% { outline-color: #facc15; }
  100% { outline-color: transparent; }
}

​

Duration and Timeout

• Default highlight duration: 3 seconds
• Element is automatically cleared of the class after animation completes
• If the user hovers over the highlighted element, the animation should pause or extend visibility

​

User Feedback & Interaction

​

Accessibility Considerations

• Avoid blinking, flashing, or seizure-inducing effects
• Ensure that screen readers are not distracted or misrouted by hidden visual overlays
• Highlighted areas must remain keyboard-accessible if tabbed

​

Error Handling

​

API/AI Format (Integrated with Scroll)

{
  "action": "scroll",
  "target": "#faq-section",
  "highlight": true,
  "message": "Here’s the answer to your question on returns."
}

​

Storage and Analytics

​

Success Criteria

• ≥ 90% of valid scrolls are followed by correctly rendered highlight animation
• Animation completes smoothly on all modern browsers
• Highlight is visually noticeable but non-intrusive
• No DOM errors occur from missing or malformed target elements
• User engagement (scroll, dwell, or click) increases on highlighted content

​

5.4 Navigation Control

​

Purpose

​

User Story

• As a user, I want the assistant to move me to another page (e.g., “Show me your services”) so I don’t have to search for the right menu or link.
• As a returning user, I want to continue our conversation after the new page loads without restarting the assistant or losing context.

​

Functional Requirements

​

Link Resolution

• When the LLM responds with a navigation instruction, the payload should contain:

{
  "action": "navigate",
  "target": "/pricing",
  "message": "Let’s go to the pricing page so I can show you."
}

• The assistant must:
  1. Confirm the destination is a valid internal path (same domain only)
  2. Prevent navigation loops or invalid URLs
  3. Delay execution by 500–1000ms to allow the AI message to display
  4. Trigger window.location.href = target (or history.pushState for SPAs if supported)

​

Session Preservation

• Before navigation:
  • Current session ID is saved to localStorage
  • Conversation history is serialized and stored locally and (optionally) in Supabase
  • Target page URL is stored in session.lastRoute
• On page load:
  • Widget checks for siteguide_session_id and siteguide_lastRoute
  • Chat window automatically restores:
    • Previous messages
    • Scroll position (if provided)
    • Assistant open state (if chat was open before reload)

​

Widget State Behavior

​

Trigger Events

​

UI/UX Requirements

• Assistant must confirm intent and give user a second to absorb message before switching pages.
• Optional: display a loading spinner inside the assistant avatar during page change.
• Upon reload, assistant should say something like: “We’re here. Let me show you the section I mentioned.”

​

Implementation Flow

1. User asks: “What services do you offer?”
2. AI responds with message + navigate action to "/services"
3. Assistant shows reply: “Let’s go to the services page so I can show you.”
4. Assistant waits 750ms
5. `window.location.href = "/services"`
6. On page load:
   - SiteGuide reads session ID from localStorage
   - Restores prior memory, conversation, open state
   - Initiates follow-up scroll/highlight (if instructed)

​

Error Handling

​

Developer Notes

• Navigation can be triggered either:
  • From AI (navigate action)
  • Or internally, via assistant UI button (e.g., “Take me to pricing” prompt)
• Must integrate with existing scroll/highlight stack: if AI wants to scroll after navigation, target selector must be checked on new page and delayed until DOMContentLoaded.

​

Success Criteria

• ≥ 90% of internal navigation attempts succeed without user confusion
• Chat session resumes within 1 second after page load
• User never sees a blank chat window unless starting fresh
• No flicker or loss of assistant UI state
• Users complete multi-page journeys without needing to re-initiate conversation

​

5.5 Voice Input and Output

​

Purpose

1. Speak to the assistant instead of typing
2. Hear spoken responses from the assistant rather than reading

​

User Story

• As a mobile visitor, I want to speak my question and hear the assistant’s answer, so I can browse the site without typing.
• As a desktop user with limited mobility or accessibility needs, I want the assistant to be operable by voice commands alone.

​

Functional Requirements

​

Voice Input (Speech-to-Text)

• Triggering Voice Input:
  • Microphone icon is present in the assistant input bar.
  • Clicking the mic activates live transcription via Web Speech API.
  • Optional “voice activation phrase” (e.g., “Hey SiteGuide”) is not required for MVP.
• Transcription Behavior:
  • While listening, UI shows an animated waveform or listening animation.
  • Partial results may be shown (if supported by browser).
  • When speech ends, full transcription is inserted into the input field and submitted.
  • All speech sessions are capped at 10 seconds unless paused manually.
• Supported Browsers:
  • Web Speech API is supported on most Chromium-based browsers and Safari (desktop + mobile).
  • MVP implementation will not support Firefox for voice input.
  • Feature auto-disables if unsupported.
• Fallback Detection:
  • If microphone permissions are denied, assistant displays: “I couldn’t access your microphone. You can still type your question below.”
• Security Considerations:
  • Voice input is not recorded or stored as audio.
  • Only text transcription is retained in Supabase with session data.

​

Voice Output (Text-to-Speech)

• Triggering Voice Output:
  • When voice mode is enabled in the plugin settings, assistant responses are spoken aloud using the browser’s speech synthesis engine or ElevenLabs (if configured).
• Playback Behavior:
  • Assistant reads responses in a polite, natural pace (approx. 120–150 words per minute).
  • User can interrupt playback by clicking the mic or typing.
  • Voice playback can be globally disabled by the site admin.
• Voice Customization:
  • MVP will use default browser voice.
  • Future releases may allow assistant persona selection via ElevenLabs API (e.g., “Jessie” voice, male/female tones).
• Speech Rendering Requirements:
  • Response playback begins only after full text is rendered.
  • Short delays (100–300ms) are acceptable to mimic human pacing.

​

UI/UX Requirements

​

Microphone Icon States:

​

Accessibility Considerations:

• All voice controls must be operable via keyboard
• Microphone button must have appropriate aria-label
• Visual animations must not cause flashing or seizure risk
• Voice output must be supplemented by on-screen text at all times

​

Voice Mode Toggle (Admin Control)

• Admin can globally enable/disable voice input and/or output from the WordPress plugin settings.
• Optional: site admin can choose whether voice mode is enabled by default for all users or must be toggled on manually.

// Example WordPress setting
$settings = [
  'voice_input_enabled' => true,
  'voice_output_enabled' => true,
  'default_voice_mode' => 'enabled',
];

​

Error Handling

​

State Management and Storage

• No audio files are stored.
• Transcribed speech is treated as plain user input and saved as:

{
  "message": "Do you offer same-day shipping?",
  "input_type": "voice",
  "confidence": 0.92
}

• Stored in Supabase under the same schema as typed messages, with input_type field for analytics segmentation.

​

Success Criteria

​

Technical Notes

• Web Speech API Reference:
  https://developer.mozilla.org/en-US/docs/Web/API/Web\_Speech\_API
• ElevenLabs API (Optional Phase 2):
  • Will require per-site authentication tokens
  • TTS conversion must be cached or streamed to minimize delay
• Rate Limits & Stability:
  Web Speech API is client-side and has no external rate limits, but assistant must:
  • Limit one voice session at a time
  • Handle stop/start toggles without stacking

​

5.6 Persistent Session Memory

​

Purpose

• Resume conversations across page reloads
• Recollect prior questions, answers, and AI actions
• Recognize returning users via stored session or email
• Maintain context during multi-page journeys

​

User Story

• As a first-time visitor, I want the assistant to remember what I’ve already asked while I navigate between pages.
• As a returning visitor, I want the assistant to pick up where we left off, even if it’s been days or weeks.
• As a business, I want to track user behavior and engagement over time without requiring accounts or logins.

​

Functional Requirements

​

Anonymous Session Initialization

• On first load:
  • Generate a siteguide_session_id (UUID v4)
  • Store in localStorage
  • Example:

localStorage.setItem('siteguide_session_id', '7c49f920-89a0-442e-8f89-a1d0e4b915bb');

• Send this session ID with every interaction (text, voice, scroll, highlight)

​

Session Memory Structure

• Each session tracks:

{
  "session_id": "abc123",
  "site_domain": "clientsite.com",
  "start_time": "2025-08-10T12:22:01Z",
  "last_active": "2025-08-10T12:45:17Z",
  "pages_visited": ["/home", "/pricing"],
  "messages": [
    { "sender": "user", "text": "What are your hours?" },
    { "sender": "ai", "text": "We’re open from 9–5, Monday through Friday." }
  ],
  "actions": [
    { "type": "scroll", "target": "#hours", "timestamp": 1691689021 }
  ],
  "status": "anonymous"
}

​

Long-Term Persistence

• Session object is upserted into Supabase every time:
  • A new message is exchanged
  • A scroll or highlight action is triggered
  • A new page is visited
• Supabase Tables:
  • sessions
  • messages
  • actions
  • page_visits

​

Rehydration on Page Load

• On load, SiteGuide checks localStorage for existing session ID
• If found, the assistant:
  • Restores conversation history into the chat window
  • Restores assistant open/closed state
  • May resume unfinished actions (e.g., if AI said “Let me show you” but page changed before scrolling)

​

Cross-Page Memory

• Memory is continuous across internal navigation:
  • Assistant state (open/closed)
  • Conversation context
  • Scroll position (if applicable)

​

Session Expiration and Archiving

• Active sessions remain “live” for 6 months from last interaction
• After expiration:
  • Marked as archived in Supabase
  • Can still be referenced for analytics or email-linked retrieval
• Sessions that exceed 1MB in size (e.g., very long threads) are truncated server-side to retain only summary and metadata

​

Memory Scope and Depth

​

What the Assistant Remembers:

​

What is not retained:

• Exact scroll positions unless requested
• Audio recordings (voice input is always discarded after transcription)
• Any third-party cookies or cross-site tracking data

​

Error Handling

​

Security and Privacy

• Session IDs are anonymous by default
• If a user provides their email, it is explicitly linked to the session in Supabase:

{
  "session_id": "abc123",
  "user_email": "user@example.com",
  "status": "identified"
}

• Sessions can only be resumed via:
  • Same browser/device (using session ID in localStorage)
  • Or user-provided email (see Section 5.7)
• All data is stored securely in Supabase under row-level security policies
• No sensitive data is ever sent to the LLM or frontend without explicit user input

​

Developer Implementation Notes

• Memory manager should be implemented as a standalone module (e.g., SessionMemory.js)
  • Exports: startSession(), saveInteraction(), rehydrate(), syncWithBackend()
• Syncing strategy: use a debounce mechanism (e.g., save every 1 second max) to avoid flooding the DB
• Versioning: memory schema should support future enhancements (e.g., per-user profiles, analytics enrichment)

​

Success Criteria

​

User Story

• As a user, I want to provide my email so I can return later and pick up the conversation where I left off.
• As a user, I want to be able to say “remember me” and not start from scratch every time I come back to the site.
• As a business owner, I want to retain high-value customer sessions and build longer-term relationships without requiring logins or signups.

​

Functional Requirements

​

Email Prompt Flow

                                   “Would you like me to remember you for next time?” |

​

Data Collection

• When user provides an email, associate it with current session in Supabase:

{
  "session_id": "abc123",
  "user_email": "user@example.com",
  "status": "identified"
}

• Validate email format client-side before sending (basic regex)
• Only one email may be linked per session (no overwrites)
• Backend lookup enables session merges in the future (see below)

​

Return Visit Flow

                                    “Welcome back! Picking up from where we left off...” |

​

Assistant Messaging UX

• Initial prompt: “Would you like me to remember our conversation for next time? I can do that with just your email.”
• On success: “Great, I’ll remember you! You can come back anytime and we’ll pick up where we left off.”
• On error or no matching session: “Looks like I couldn’t find your previous session. No worries—we can start fresh.”

​

Database Behavior

• sessions table: adds a user_email column (unique per active session)
• Index user_email for fast lookup
• Retention policy: all email-linked sessions are preserved for 12 months unless deleted

​

Optional: Session Merge

• When a known user returns and creates a new anonymous session:
  • Check for user_email match
  • Optionally merge previous messages and metadata into new session
  • Flag session as merged_from: [old_session_id] for auditing

​

Developer Implementation

​

Frontend

• Memory module should expose:

saveEmailToSession(email)
checkForEmailLinkedSession(email)

• Assistant must allow user to enter email via:
  • Natural conversation (“remember me”)
  • Manual form input if AI requests it
  • External injection (e.g. pre-fill from site login if available)
• Conversation history should hydrate from Supabase if no local session is available and email match is found.

​

Backend

• Supabase table schema:
  • session_id (UUID)
  • user_email (VARCHAR, indexed)
  • created_at
  • last_active
  • status (anonymous | identified)
  • merged_from (nullable)
• API endpoints:
  • GET /session/by-email?email=... → returns last active session
  • POST /session/link-email → links email to session

​

Security & Privacy

• Email is opt-in only; never stored or associated without explicit user input
• User can request deletion of email-linked session (future feature)
• Emails are stored securely in Supabase with access controls and encryption-at-rest
• Assistant must never send outbound emails—storage is for internal continuity only unless integrated with CRM/email tools

​

Error Handling

​

Success Criteria

​

5.8 Memory Summary and AI Recall Behavior

​

Purpose

​

User Story

• As a user, I want the assistant to remember key things I’ve said or asked about, like my goals or interests.
• As a user, I want the assistant to provide coherent, personalized responses instead of repeating generic info.
• As a developer, I want to ensure only the most useful context is passed to the LLM to reduce cost and improve precision.

​

Memory Architecture

​

Layers of Memory

​

Summary Format

{
  "goals": ["Learn about pricing", "Find out if there's a demo"],
  "interests": ["Small business SEO", "Weekly blog publishing"],
  "name": "Bob",
  "preferences": {
    "chatStyle": "direct and friendly",
    "followUps": true
  },
  "last_visited": "/features",
  "last_action": "Requested pricing guide",
  "timestamps": {
    "created": "2025-08-10T14:05:00Z",
    "updated": "2025-08-11T10:42:00Z"
  }
}

​

Context Injection Logic

• Upon every message, SiteGuide assembles a payload that includes:
  • Last 5–10 user/assistant messages (chronological)
  • Memory summary (inserted via system prompt or initial instruction)
• Example:

SYSTEM: The user is named Bob. He’s interested in SEO tools and asked about pricing. Be direct and friendly.

• Summaries are updated:
  • After significant topic changes
  • When user expresses a new goal (e.g., “I’m also interested in eCommerce”)
  • Upon assistant action (e.g., navigates to pricing page)

​

Memory Update Triggers

​

Developer Responsibilities

• Create a memory controller module that:
  • Listens for state changes and conversation events
  • Writes updated summaries to Supabase per session ID
  • Provides a getMemorySummary(session_id) function
• Memory summary is cached client-side in case of Supabase lag
• Provide a dev interface to manually inspect/edit summaries (admin view)

​

LLM Prompt Injection Behavior

​

Error Handling

​

Success Criteria

​

5.9 Scroll, Highlight, and DOM Interaction Features

​

Purpose

• Scroll the page to focus user attention
• Highlight specific sections or elements
• Point to content as it’s discussed
• Manipulate navigation contextually without breaking session flow

​

User Story

• As a user, I want the assistant to move the screen for me when it refers to something so I don’t have to search.
• As a user, I want the assistant to highlight what it’s talking about so I’m never confused.
• As a user, I want to see visual feedback when I click on a suggestion from the assistant.

​

Functional Requirements

​

5.9.1: Scroll to Element

​

Behavior

• When referencing a part of the page (e.g. “the pricing table”), SiteGuide will automatically scroll to that section smoothly.
• Scroll is performed using element.scrollIntoView({ behavior: 'smooth' }).

​

Trigger Methods

​

Development Needs

• Selector dictionary (semantic label → CSS selector)
• Scroll action throttle (avoid spamming on rapid interactions)
• Scroll offset for fixed headers (allow config, e.g. 80px)

​

5.9.2: Element Highlighting

​

Behavior

• Flash or outline key element for visual guidance
• Use temporary box-shadow or outline animation
• Duration: 3–5 seconds, then fade unless reactivated

​

Trigger Methods

​

Development Needs

• Overlay module or dynamic class injection
• Prevent highlight on invisible elements (use getBoundingClientRect())
• Accessibility: ensure visual styles don’t conflict with WCAG standards

​

5.9.3: Pointer/Arrow Overlay (Optional)

​

Behavior

• Display a temporary floating arrow or pointer next to the element the assistant is referencing
• Appears for 3–10 seconds and points toward the DOM node
• Can pulse, animate, or tilt for visibility

​

Use Cases

• On complex pages with many elements (e.g. dashboards)
• On user request (“Can you show me where that is?”)

​

Development Needs

• Overlay container for pointer component
• Arrow follows DOM element if page resizes or scrolls
• Lightweight implementation (no external pointer libraries required)

​

5.9.4: DOM-Based Navigation and Clicking (Optional but Recommended)

​

Behavior

• Assistant can trigger a click on a known element when instructed to “take me there,” “show me that,” or “open it”
• Simulates a user click or link activation, e.g.:

document.querySelector("#pricing-btn")?.click()

​

Use Cases

• Streamlines flow from chat to action
• Allows users to treat the assistant as a remote control

​

Risk Management

• Add safeguards to avoid clicking payment buttons, form submissions, etc.
• Use whitelist of click-safe selectors only

​

Development Needs

• Click controller module
• AI output parser that detects action-intent messages
• Optional confirmations: “Click now?” → [Yes] [No]

​

5.9.5: Multistep Visual Tours (Optional)

​

Behavior

• Assistant walks user through a guided tour by:
  • Scrolling to a section
  • Highlighting key points
  • Explaining verbally
  • Offering to continue: “Next step?” → scrolls again

​

Use Cases

• Onboarding for new visitors
• Product walk-throughs
• Multi-part navigation (e.g. blog + pricing + contact)

​

Development Needs

• Tour script JSON format:

[
  {
    "selector": "#hero",
    "message": "Here’s where you’ll see our main promise."
  },
  {
    "selector": "#features",
    "message": "Now scroll down to the features section."
  }
]

• Progress state manager (tracks tour steps)
• User override: “skip” or “pause tour”

​

Developer Implementation

​

Core Methods Required

function scrollToSelector(selector, offset = 0) { ... }
function highlightElement(selector, duration = 5000) { ... }
function clickElement(selector) { ... }
function showPointerOverlay(selector) { ... }
function runTour(stepsArray) { ... }

​

Example: AI Triggers Highlight & Scroll

{
  "type": "scroll-highlight",
  "selector": "#pricing-table"
}

​

Error Handling

​

Success Criteria

​

5.10 Multilingual and Accessibility Support

​

Purpose

• Speak different native languages
• Use assistive technologies (screen readers, keyboard navigation, etc.)
• Have visual, auditory, cognitive, or motor impairments

​

User Story

• As a non-English speaker, I want the assistant to respond in my language automatically, so I can use the site comfortably.
• As a user with visual impairment, I want to be able to interact with the assistant and understand its responses using screen readers.
• As a keyboard-only user, I want to be able to navigate all features of the assistant without using a mouse.

​

5.10.1 Multilingual Support

​

Detection and Configuration

​

Supported Languages (Initial Phase)

• English (default)
• Spanish
• French
• German
• Portuguese
• Hindi
• Arabic
• Mandarin Chinese

​

Assistant Behavior

• Detects language preference automatically
• Responds and summarizes content in that language
• Translates webpage content using embedded summaries or scraped metadata
• UI buttons and prompts must also be localized

​

LLM Integration

• Use OpenAI’s GPT-4o or similar multilingual LLMs
• Responses should respect the grammatical and formal norms of each language
• Language-specific fallback phrases must be predefined in case of AI errors

​

Developer Needs

• Language file system (e.g. /locales/en.json, /locales/es.json)
• Context language injection into all AI messages
• AI model routing if required for localization quality

​

5.10.2 Accessibility Support (WCAG 2.2 Compliance)

​

Key Principles

• Perceivable: Users must be able to perceive the interface
• Operable: Interface must be operable via keyboard, voice, etc.
• Understandable: Language and visuals must be clear
• Robust: Must work across a wide range of assistive tech

​

Specific Requirements

​

Live Region Example:

<div aria-live="polite" role="log" id="chat-feed">
  <div role="alert">Assistant: Here’s your pricing guide.</div>
</div>

​

Developer Guidelines

​

HTML/JS Requirements

• Tab-index order must follow logical flow
• All buttons and interactive areas must have:
  • aria-label
  • role
  • Fallback keyboard equivalents
• Modal dialogs (e.g., language selection) must trap focus until dismissed

​

CSS Guidelines

• Respect prefers-reduced-motion user settings
• No text inside decorative images
• Tooltips and instructional overlays must have text alternatives

​

Analytics & Error Handling

• It should respond with: “I’m still learning that language, but I can try English or Spanish for now.”

• Developer must log and fix within patch window.

​

Success Criteria

​

5.11 Persistent Sessions and Context Recovery

​

Purpose

​

User Story

• As a user, I want to leave the site and come back later without starting over.
• As a returning visitor, I want SiteGuide to remember my name, goals, and last conversation.
• As a business owner, I want returning users to feel like they’re building a relationship with my brand.
• As a developer, I want a reliable way to associate persistent memory to unique users—even anonymously if needed.

​

5.11.1 Session Identification

​

5.11.2 Session Data Stored

​

Fields Tracked per Session

{
  "session_id": "user-xyz-abc",
  "email": "example@example.com",
  "name": "Sarah",
  "first_seen": "2025-08-01T10:00:00Z",
  "last_seen": "2025-08-11T15:22:00Z",
  "last_page": "/pricing",
  "memory_summary": {
    "goals": ["Compare plans", "Understand SEO support"],
    "preferences": {
      "language": "en",
      "chatStyle": "fast and casual"
    }
  },
  "interaction_count": 14,
  "last_chat_log": [...],
  "version": "1.4.0"
}

​

5.11.3 Storage System Design

​

5.11.4 Session Resumption Workflow

​

For Anonymous Users (local device)

1. On return, check localStorage for UUID
2. If found, restore from Supabase using UUID
3. Rehydrate assistant memory and chat UI
4. Resume conversation or greet with summary: “Welcome back! Last time we were comparing plans. Want to pick up where we left off?”

​

For Identified Users (email match)

1. Ask: “Want to continue where we left off?”
2. Rehydrate structured memory
3. Reload final chat log (optional)
4. Use language, preferences, and goals from prior memory immediately

​

For Logged-in WordPress Users

1. Auto-detect user ID via WP API
2. Bypass chat intro and resume based on ID-linked session
3. Add support for personalized dashboards

​

5.11.5 Recovery Triggers

​

5.11.6 Developer Responsibilities

• Ensure a sessionController module handles:
  • Generation and storage of anonymous UUID
  • Email-to-session mapping in Supabase
  • Full memory summary and chat history synchronization
• Provide a fallback if session cannot be recovered
  • Fallback message: “I couldn’t find your last session, but I’m happy to help you start again!”
• Build a resumeSession() function that:
  • Loads memory
  • Rehydrates UI
  • Sends system prompt to LLM with memory context
• Provide admin interface to view, edit, or delete session data manually

​

5.11.7 Analytics and Metrics

​

5.11.8 Security and Privacy

• No sensitive personal data beyond name/email/goals
• Users can delete their session by saying “delete my data”
• Optional GDPR module for account data requests
• All session data encrypted at rest in Supabase

​

Success Criteria

​

5.12 Integration with Lead Capture and Marketing Systems

​

Purpose

​

User Story

• As a business owner, I want SiteGuide to collect names, emails, and questions from visitors, so I can follow up with them.
• As a user, I want to be able to ask a question, leave my email, and get a response later if needed.
• As a marketer, I want all captured data sent to my CRM, email platform, or Google Sheet automatically.

​

5.12.1 Data Points to Capture

​

5.12.2 Capture Triggers

​

5.12.3 CRM / Marketing Integrations

​

Built-in Webhook Support

• SiteGuide can send captured leads to:
  • Zapier webhook (customizable)
  • Make.com scenarios
  • N8N workflows (recommended for aiConnected users)
  • Direct Supabase table (optional internal DB)
  • Google Sheets (for MVP setups)
  • HubSpot / Mailchimp / ActiveCampaign via API/webhook

​

Recommended Flow with aiConnected:

1. SiteGuide captures lead in chat
2. Sends data to n8n webhook
3. Workflow:
   • Validates email
   • Adds to Supabase or CRM
   • Triggers email automation or follow-up alert

​

5.12.4 Consent and Confirmation

• When user gives email, SiteGuide should say: “Got it! We’ll only use your email to follow up about your question.”
• All messages involving capture should reflect GDPR/CAN-SPAM compliance if needed.
• Optional: add a small “Why are we asking this?” hover tooltip near form prompts.

​

5.12.5 Lead Scoring Logic (Optional)

• Page visited (e.g., /pricing > +5)
• Number of messages exchanged (>10 = +2)
• Use of commercial keywords like “quote,” “pricing,” “demo” (+10)
• Email collected (+10)

{
  "lead_score": 25,
  "hot": true
}

​

5.12.6 Data Enrichment (Optional)

• If user provides a business email (e.g., sarah@acmeinc.com), trigger background enrichment via Clearbit or similar
• Enrichment returned:
  • Company size, industry, revenue
  • Social profiles
  • Location
• Displayed to admin in lead dashboard or passed through to CRM

​

5.12.7 Admin Access to Captured Leads

​

5.12.8 Developer Implementation

• Create a leadCapture() function inside the SiteGuide assistant framework
• Trigger logic based on chat content, intent detection, or explicit prompts
• Add native email validation
• Send structured data to endpoint(s) via:
  • HTTP POST
  • Supabase insert
• Ensure assistant UI shows success/failure feedback (e.g., “Thanks! We’ll be in touch.”)
• Add fallback for offline mode: store lead locally and sync when online

​

5.12.9 Success Criteria

​

5.13 Analytics and Performance Tracking

​

Purpose

​

User Story

• As a business owner, I want to see how many users are interacting with my AI assistant, what they’re asking, and how often it leads to conversions.
• As a marketing manager, I want to know which pages have the highest engagement and where to improve lead capture.
• As a developer, I want to log all system events and errors for debugging and performance optimization.

​

5.13.1 Data to Track

​

5.13.2 Tracking Infrastructure

​

Database Tables (Supabase)

• sessions: Stores session IDs, start/end time, user ID (if known), and page source
• messages: Logs all assistant/user exchanges with timestamp, category, language
• events: Logs scrolls, highlights, clicks, lead capture, and other user actions
• leads: See Section 5.12 – includes source, intent tag, timestamps, score
• errors: Tracks all system exceptions, API timeouts, and integration failures

​

Real-Time Analytics Pipeline

• Optional: Mirror events to PostHog, Plausible, or Segment for enhanced dashboards
• Create a Supabase view or materialized table for:
  • Daily active users
  • Lead conversion rate
  • Average response time
  • Top 10 queries

​

5.13.3 Developer Implementation Plan

1. Tracking Library
   • Create analytics.ts utility with functions like trackEvent(), logMessage(), recordError()
   • Include session UUID in every call
   • Automatically log startSession() on assistant open
2. Frontend Hook
   • Use a centralized analytics handler (e.g., React Context or Vue plugin)
   • Trigger on assistant events like:
     • Message sent
     • Message received
     • Page scrolled
     • Element clicked
     • Input field shown
     • Lead form submitted
3. Supabase Write
   • Use Supabase client to write rows to relevant tables in real time
   • Implement rate-limiting/batching if needed
   • Use row-level security tied to domain/project
4. External API Forwarding (Optional)
   • If client uses Segment, allow event forwarding
   • Setup event mirror with filters to external destinations (PostHog, GA4, etc.)