Beezaro Copilot Architecture

📋 See Also: Manual Onboarding

🤖 BEEZARO CONVERSATIONAL ONBOARDING - OVERVIEW

Alternative AI-Powered Chat Interface for User Onboarding (Mirrors Manual Steps 0-8)

🎯 What is Beezaro Copilot?

Beezaro is a conversational AI assistant that guides users through the entire onboarding process via natural language chat instead of traditional forms.

Key Points:

✅ Same data collected as Manual Onboarding - Different UX, same outcome
✅ Natural Q&A interface - Users answer questions in chat, not forms
✅ Smart recommendations - AI suggests settings based on plan tier & industry
✅ Seamless fallback - When user says "No" or "Skip", opens corresponding manual screen
✅ Progress tracking - Users can switch between copilot ↔ manual anytime
✅ Multi-device responsive - Desktop, Mobile App, Web Responsive versions

📝 MANUAL ONBOARDING

                            1. Sign Up (Email/OAuth)

                            2. Email Verification

                            3. Plan Selection

                            4. Business Information Form

                            5. Team Setup Form

                            6. AI Assistant Form

                            7. Channel Integration Form

                            8. Per-Channel Config Form

                            9. Webchat Setup Form

                            10. Automation Templates Form

                            ✅ Complete

UX: Form-based, step-by-step wizard

🤖 BEEZARO COPILOT

                            PRE-BEEZARO (Manual STEP 0):

                            1. Sign Up (Email/OAuth)

                            2. Email Verification

                            3. Plan Selection

                            BEEZARO FLOW:

                            STEP 0: Welcome & Mode Selection

                            STEP 0.5: Beezaro Intro Modal

                            STEP 1: Business Identity (plan confirmation)

                            STEP 2: Team Members

                            STEP 3: Channels

                            STEP 4: Fall-Back Logic

                            STEP 5: AI Assistant

                            STEP 6: Automation

                            7. Review & Confirm

                            ✅ Complete

UX: Conversational, guided chat with STEP 0 & 0.5 fallback options

🔄 CRITICAL FALLBACK LOGIC (When User Says "No")

Example Workflow:

Beezaro asks: "What's your business name?"
User types: "No" or "Skip"

System detects fallback trigger
→ Logs to `copilot_fallback_triggers` table
→ Updates `onboarding_state.onboardingMode = 'manual'`

Redirects to Manual Screen
→ Opens: Manual STEP 2 - Business Name input screen
→ Shows "Return to Beezaro" button at top

User completes field manually
→ Enters: "GreenLeaf Pharmacy"
→ Saves to `organizations.business_name`
→ Updates `onboarding_state.collectedData`

Returns to Beezaro chat
→ User clicks "Return to Beezaro"
→ Updates `onboarding_state.onboardingMode = 'copilot'`
→ Beezaro: "Great! I see you entered GreenLeaf Pharmacy. Next question..."

🎯 Key Insight: User has complete control. Can switch between chat and forms anytime. All data syncs automatically via `onboarding_state` table.

📋 "View in manual setup" Button Availability:

Always visible on EVERY Beezaro step (STEP 1-6)
Displayed as secondary/outline button below quick response options
User can click at any time, not just when saying "No"
Clicking opens corresponding manual screen for detailed configuration
User completes manual form → Clicks "Return to Beezaro" → Resumes chat
Proactive option: Gives users choice without requiring decline

🚀 STEP 0 & 0.5: Entry Points (Critical Fallback Opportunities)

STEP 0: Welcome & Mode Selection

Screen: "Setup up your account"

UI File: Welcome screen.png

3 CTAs:

"Let Beezaro Set Everything Up For Me" (Green - Recommended) → STEP 0.5
"Customize It Myself Instead" (Yellow/Orange) → Full Manual Setup
"Skip for now" (White/Secondary) → Exit setup entirely

🚨 Critical Fallback: "Customize It Myself Instead" bypasses Beezaro entirely and enters full manual onboarding

Database: Logs choice to onboarding_state.onboardingMode ('copilot' or 'manual')

STEP 0.5: Beezaro Intro Modal

Beezaro Says: "Hi there! I'm Beezaro. I'll set everything up for you in just a few questions. Ready?"

UI File: BeeBot Intro.png

2 Options:

"Yes, let's go" (Green button) → STEP 1 (Business Identity)
"Show me the manual setup instead" (Secondary link button) → Full Manual Setup

🚨 Early Exit: User can switch to manual setup BEFORE any questions are asked

API Endpoint: POST /api/copilot/start (initializes copilot_sessions)

📋 Beezaro Onboarding Steps (6 Main Steps)

Business Identity

Questions:

Confirm plan selection
Business name
Industry
Business description
Upload logo
Knowledge base files/URL

Fallback: Opens Manual STEP 2

Team Members

Questions:

Add team members?
How many?
Enter emails
Assign roles per member

Fallback: Opens Manual STEP 3

Channels

Questions:

Select channels (grid)
Configure now or defaults?
Per-channel settings

Fallback: Opens Manual STEP 5

Escalation Rules

(Also called "Fall-Back Logic" in UI)

Questions:

What if no reply?
Wait / Escalate / Follow-up
Delay configuration

Fallback: Opens Manual STEP 6 (Escalation Rules)

AI Assistant

Questions:

Single or multiple?
AI name
Tone selection
Personality type

Fallback: Opens Manual STEP 4

Automation

Questions:

Add starter automation?
Which category?
Select template
Activate?

Fallback: Opens Manual STEP 8

🎨 Beezaro UI Components (From 226 UI Screens)

Core Components

Chat Interface: Left panel (animated Beezaro bee), Right panel (conversation)
Progress Stepper: Visual indicator across top (6 steps)
Quick Response Buttons: Inline option cards with radio buttons
Preview Modal: Review collected data before confirming
Fallback CTA: "View in manual setup" button (always visible)
Exit Button: Save progress and return later (Red "X Exit" button, top left)
Command Bar: Advanced settings accordion (Available AFTER completion)

Device Variants

Desktop: Side-by-side chat + preview (58 screens)
Mobile App: Full-screen chat, modal previews (84 screens)
Web Responsive: Adaptive layout (84 screens)
iPad: Hybrid layout

Total UI Screens: 226 screens across all devices

🎛️ Command Bar (Advanced Settings - Post-Onboarding)

When Available: Command bar appears AFTER Beezaro setup completion, accessible from dashboard settings.

Purpose: Allows users to edit all settings configured during Beezaro onboarding with granular control.

Accordion Sections:

Business Identity - Edit name, industry, description, logo
Team Members - Add/remove members, change roles
Channels - Configure per-channel settings with tabs (WhatsApp, Webchat, Instagram, Shopify)
AI Assistant - Edit name, tone, personality per channel
Escalation Rules - Toggle switch for enabling/disabling
Follow-Up Triggers - Toggle switch for timing controls
AI Behavior Settings (Timing) - Toggle switch for response delays
Access Permissions - Toggle switch for team permissions
Beezaro Live Test - Button to test AI replies on each channel
Automation - Edit automation rules and templates

Note: Command bar is NOT visible during guided Beezaro flow to avoid overwhelming users. It becomes available after setup completion in the main dashboard.

UI File Reference: Command bar.png (Desktop accordion menu)

🤖 BEEZARO BACKEND SERVICES & API ENDPOINTS

💻 SWIM LANE 1: BEEZARO BACKEND SERVICES (3 New Services)

💬 Beezaro Conversational Service

Purpose:

Handle all conversational onboarding interactions via natural language chat interface

Core Features:

• Natural Language Understanding (NLU): Parse user text input using OpenAI GPT-4
• Intent Detection: Classify user response (provide_info | skip | fallback | need_help | confirm)
• Entity Extraction: Extract structured data from unstructured text (e.g., business name from "My company is GreenLeaf")
• Context Management: Maintain conversation state across multiple messages
• Step Routing: Determine next question based on current step & user responses
• Fallback Detection: Trigger redirect to manual when user says "No", "Skip", or unclear input
• Session Persistence: Save/resume conversations (user can leave and return)

AI Integration:

• Provider: OpenAI GPT-4 (gpt-4-turbo-preview)
• System Prompt: "You are Beezaro, a friendly AI assistant helping users set up UnifiedBeez..."
• Context Window: Include last 10 messages + user profile + current step
• Structured Output: JSON format {intent, extracted_data, next_question, confidence}
• Few-Shot Examples: Provide examples for each onboarding step

API Endpoints:

Session Management:
• POST /api/copilot/start - Start new Beezaro session
  Body: {userId, organizationId, deviceType}
  Returns: {sessionId, firstQuestion, currentStep}

Conversation:
• POST /api/copilot/message - Send user message & get Beezaro response
  Body: {sessionId, message, timestamp}
  Returns: {beezaroResponse, intent, extractedData, nextStep}

• GET /api/copilot/conversation/:sessionId - Get full conversation history
  Returns: {messages[], currentStep, progressPercentage}

Step Control:
• POST /api/copilot/skip-step - Skip current step
  Body: {sessionId, stepName, reason}
  Returns: {nextStep, nextQuestion}

Fallback:
• POST /api/copilot/trigger-fallback - Trigger manual screen redirect
  Body: {sessionId, fromStep, reason}
  Returns: {manualScreenUrl, returnToken}

Resume:
• POST /api/copilot/resume/:sessionId - Resume paused session
  Returns: {conversationHistory, currentStep, lastMessage}

Exit & Save:
• POST /api/copilot/exit-and-save - Save progress when user clicks "Exit" button
  Body: {sessionId, userId, currentStep, collectedData}
  Returns: {resumeUrl, progressPercentage, savedAt}
  Updates: copilot_sessions.status = 'paused', onboarding_state.collectedData

• GET /api/copilot/resume-url/:userId - Get resume URL for incomplete setup
  Returns: {hasIncompleteSetup: boolean, resumeUrl: string, lastActiveStep: string}

Progress:
• GET /api/copilot/progress/:userId - Get onboarding completion status
  Returns: {completedSteps[], currentStep, progressPercentage, collectedData}

Technology Stack:

• Framework: NestJS (TypeScript)
• AI SDK: OpenAI Node.js SDK
• Validation: class-validator + class-transformer
• Caching: Redis (conversation context cache, 5-minute TTL)
• Queue: BullMQ (async AI processing)

📊 Onboarding State Management Service

Purpose:

Track user progress across BOTH manual and copilot onboarding modes. Enable seamless switching.

Core Features:

• Unified State Tracking: Single source of truth for onboarding progress
• Mode Switching: Handle copilot ↔ manual transitions without data loss
• Progress Calculation: Real-time % completion across all steps
• Data Synchronization: Merge data collected in either mode
• Partial Completion: Save incomplete steps, resume later
• Step Validation: Verify required data collected before marking step complete

API Endpoints:

State Retrieval:
• GET /api/onboarding/state/:userId - Get current onboarding state
  Returns: {mode, stepsCompleted[], currentStep, collectedData, progressPercentage}

State Updates:
• PATCH /api/onboarding/state/:userId - Update state
  Body: {stepName, data, isComplete}
  Returns: {updatedState, progressPercentage}

Mode Switching:
• POST /api/onboarding/switch-mode - Switch between copilot ↔ manual
  Body: {userId, fromMode, toMode, reason}
  Returns: {newMode, redirectUrl, syncedData}

Resume:
• GET /api/onboarding/resume/:userId - Get where to resume
  Returns: {currentMode, currentStep, nextAction}

Completion:
• POST /api/onboarding/complete/:userId - Mark onboarding complete
  Body: {finalVerification: true}
  Returns: {isComplete: true, completedAt, redirectToDashboard}

State Synchronization Logic:

Scenario: User switches from Copilot to Manual
1. User in copilot, completes Business Identity
2. User says "No" to Team Members question
3. System triggers fallback
  → Update `onboarding_state.onboardingMode = 'manual'`
  → Update `onboarding_state.lastSwitchedAt = NOW()`
  → Redirect to Manual STEP 3 (Team Setup)
4. Manual screen loads, reads `onboarding_state.collectedData`
  → Pre-fills any data already collected
5. User completes manual form, saves to DB
  → Update `onboarding_state.collectedData` with new data
  → Update `onboarding_state.stepsCompleted[]` add "team_members"
6. User clicks "Return to Beezaro"
  → Update `onboarding_state.onboardingMode = 'copilot'`
  → Resume copilot session, continue to next step

🧠 AI Response Generation Service

Purpose:

Generate dynamic, context-aware Beezaro responses personalized to user's plan tier, industry, and conversation history

Core Features:

• Personalized Greetings: "Hi [Name], I'm Beezaro!"
• Context-Aware Questions: Adjust based on plan tier (e.g., Business plan users get team questions, Individual plan skips)
• Confirmation Messages: "Got it! Your business name is [Name]"
• Recommendations: "I recommend Multiple Assistants by Channel for your Business plan"
• Error Handling: "I didn't catch that. Could you try again or type 'skip'?"
• Progress Updates: "Great! We're 60% done. Next up: Team Members"
• Industry-Specific Suggestions: "Since you're in E-commerce, I recommend these automations..."

API Endpoints:

• POST /api/copilot/generate-response - Generate Beezaro's next message
  Body: {sessionId, userMessage, currentStep, context}
  Returns: {beezaroMessage, intent, suggestedActions[]}

• POST /api/copilot/validate-input - Validate user input against schema
  Body: {stepName, userInput, expectedType}
  Returns: {isValid, extractedValue, errorMessage}

AI Prompt Templates (Per Step):

Step 1: Business Identity

                                    System: You are Beezaro asking for business name.

                                    User plan: {plan_tier}

                                    Context: This is step 1 of 6.

                                    If user says unclear input, ask politely to clarify.

                                    If user says "No" or "Skip", respond: "No problem! Let's open the manual form for you."

Step 2: Team Members

                                    System: You are Beezaro asking about team setup.

                                    User plan: {plan_tier} (Team feature available: {true/false})

                                    If Individual plan, skip this step automatically.

                                    If Business/Premium/Organization plan, ask: "Would you like to add team members?"

...and 4 more step-specific templates

♻️ SWIM LANE 2: REUSED SERVICES FROM MANUAL ONBOARDING

✅ Services That Copilot Reuses (No Changes Needed)

All data-saving services are reused:
• Organization Service (save business info)
• Team Invitation Service (save team members)
• Channel Integration Services (connect channels)
• AI Assistant Configuration Service (create Beebots)
• Automation Library Service (activate templates)
• File Upload Service (logo, knowledge base files)

Copilot calls same APIs:
• POST /organizations - Save business name, industry, description
• POST /teams/invite - Add team members
• POST /channels - Connect channels
• POST /ai-assistants - Create AI assistant
• POST /automations/activate/:templateId - Activate automation

Benefit: No duplication. Copilot is a different UI layer on top of existing APIs.

🤖 BEEZARO DATABASE SCHEMA (4 New Tables)

🗄️ SWIM LANE 4: BEEZARO DATABASE TABLES

📝 TABLE: copilot_sessions (Conversation Sessions)

Column

Type

Constraints

Purpose

SERIAL

PRIMARY KEY

Session identifier

userId

INTEGER

NOT NULL, FK → users.id

Which user owns this session

organizationId

INTEGER

NULLABLE, FK → organizations.id

Associated organization (created during session)

sessionId

UUID

UNIQUE NOT NULL

Public session identifier (for API calls)

currentStep

VARCHAR(50)

NOT NULL

status

VARCHAR(20)

DEFAULT 'active'

active | paused | completed | abandoned

startedAt

TIMESTAMP

DEFAULT NOW()

When session began

lastActiveAt

TIMESTAMP

DEFAULT NOW()

Last message timestamp (for detecting abandonment)

completedAt

TIMESTAMP

NULLABLE

When onboarding finished

deviceType

VARCHAR(20)

NULLABLE

desktop | mobile | tablet

createdAt

TIMESTAMP

DEFAULT NOW()

Record creation time

updatedAt

TIMESTAMP

DEFAULT NOW()

Last update time

💡 Usage Example:
When user clicks "Let Beezaro Set Everything Up For Me":
→ Create new row: {userId: 123, sessionId: "uuid-...", currentStep: "business_identity", status: "active"}
→ Return sessionId to frontend for all subsequent API calls

📊 Indexes:
• idx_copilot_user (userId) - Find user's sessions
• idx_copilot_session (sessionId) - Fast lookup by session
• idx_copilot_status (status, lastActiveAt) - Find abandoned sessions

💬 TABLE: copilot_conversation_history (Message Log)

Column

Type

Constraints

Purpose

SERIAL

PRIMARY KEY

Message identifier

sessionId

UUID

NOT NULL, FK → copilot_sessions.sessionId

Which conversation this belongs to

messageType

VARCHAR(20)

NOT NULL

beezaro | user | system

messageContent

TEXT

NOT NULL

Actual message text

stepContext

VARCHAR(50)

NULLABLE

Which step this message belongs to

intent

VARCHAR(50)

NULLABLE

provide_info | skip | fallback | confirm | need_help

extractedData

JSONB

NULLABLE

Structured data extracted from user message

timestamp

TIMESTAMP

DEFAULT NOW()

When message was sent

💡 Usage Example:
Beezaro message:
{sessionId, messageType: "beezaro", messageContent: "What's your business name?", stepContext: "business_identity"}

User response:
{sessionId, messageType: "user", messageContent: "GreenLeaf Pharmacy", stepContext: "business_identity", intent: "provide_info", extractedData: {businessName: "GreenLeaf Pharmacy"}}

📊 Indexes:
• idx_conversation_session (sessionId, timestamp) - Retrieve conversation in order
• idx_conversation_step (stepContext) - Filter by step

📊 TABLE: onboarding_state (Unified Progress Tracking)

Column

Type

Constraints

Purpose

SERIAL

PRIMARY KEY

State identifier

userId

INTEGER

UNIQUE NOT NULL, FK → users.id

One state per user

organizationId

INTEGER

NULLABLE, FK → organizations.id

Associated organization

onboardingMode

VARCHAR(20)

DEFAULT 'copilot'

copilot | manual (current mode)

stepsCompleted

JSONB

DEFAULT '[]'

Array of completed step names

currentStep

VARCHAR(50)

NULLABLE

What step user is currently on

collectedData

JSONB

DEFAULT '{}'

All data collected so far (from either mode)

lastSwitchedAt

TIMESTAMP

NULLABLE

When user last switched between copilot ↔ manual

progressPercentage

INTEGER

DEFAULT 0

0-100 completion percentage

isCompleted

BOOLEAN

DEFAULT FALSE

Has user finished entire onboarding?

startedAt

TIMESTAMP

DEFAULT NOW()

When onboarding began

completedAt

TIMESTAMP

NULLABLE

When onboarding finished

createdAt

TIMESTAMP

DEFAULT NOW()

Record creation

updatedAt

TIMESTAMP

DEFAULT NOW()

Last update

💡 Usage Example (Mode Switching):
Initial State (Copilot):
{userId: 123, onboardingMode: "copilot", currentStep: "business_identity", stepsCompleted: [], collectedData: {}}

After completing Business Identity in copilot:
{onboardingMode: "copilot", currentStep: "team_members", stepsCompleted: ["business_identity"], collectedData: {businessName: "GreenLeaf", industry: "Healthcare"}}

User says "No" to team question → Switches to manual:
{onboardingMode: "manual", currentStep: "team_members", lastSwitchedAt: NOW()}

After completing team in manual → Returns to copilot:
{onboardingMode: "copilot", currentStep: "channels", stepsCompleted: ["business_identity", "team_members"], collectedData: {...team data added...}}

📊 Index:
• idx_onboarding_user (userId) - One state per user

🔄 TABLE: copilot_fallback_triggers (Manual Redirect Log)

Column

Type

Constraints

Purpose

SERIAL

PRIMARY KEY

Trigger identifier

sessionId

UUID

NOT NULL, FK → copilot_sessions.sessionId

Which session triggered fallback

userId

INTEGER

NOT NULL, FK → users.id

Which user

triggerReason

VARCHAR(50)

NOT NULL

user_said_no | user_skipped | validation_failed | complex_input | unclear_response

fromStep

VARCHAR(50)

NOT NULL

Which copilot step triggered fallback

toManualScreen

VARCHAR(100)

NOT NULL

Which manual screen to open (e.g., "STEP 2 - Business Name")

returnedToChat

BOOLEAN

DEFAULT FALSE

Did user complete manual and return to copilot?

triggeredAt

TIMESTAMP

DEFAULT NOW()

When fallback occurred

resolvedAt

TIMESTAMP

NULLABLE

When user returned to copilot (or abandoned)

💡 Usage Example:
Trigger:
Beezaro: "What's your business name?"
User: "No"
→ Create row: {sessionId, userId, triggerReason: "user_said_no", fromStep: "business_identity", toManualScreen: "STEP 2 - Business Name", triggeredAt: NOW()}

Resolution:
User completes manual form, clicks "Return to Beezaro"
→ Update row: {returnedToChat: TRUE, resolvedAt: NOW()}

📊 Analytics Use:
• Count how often users fallback to manual (UX improvement insights)
• Which steps cause most fallbacks (identify problem questions)
• Return rate (do users come back to copilot after manual?)

🔄 BEEZARO ↔ MANUAL ONBOARDING MAPPING

Complete Question-to-Screen Mapping with Fallback Logic

📊 COMPLETE STEP MAPPING

Beezaro Step	Copilot Question	Manual Screen	Database Field	Fallback Trigger
STEP 1 Business Identity	"Confirm you selected [Business Plan]" (Plan already selected during signup)	Manual STEP 1 - Plan Selection (Re-selection if changed)	subscriptions.plan_id	User says "No, Change plan" → Reopens plan selection
	"What's your business name?"	Manual STEP 2 - Business Name	organizations.business_name	User says "No" or "Skip"
	"What industry is your business based?"	Manual STEP 2 - Industry Dropdown	organizations.industry	User unclear or says "Skip"
	"Tell us about your business"	Manual STEP 2 - Description	organizations.business_description	User says "No"
	"Upload your business logo"	Manual STEP 2 - Logo Upload	organizations.logo_url + S3	User says "Skip" or upload fails
	"Knowledge base files or website URL?"	Manual STEP 2 - Knowledge+Files	knowledge_base_documents	User says "Skip"
STEP 2 Team Members	"Would you like to add team members?"	Manual STEP 3 - Team Setup	team_members table	User says "No" (skip entire step)
	"Enter team member emails"	Manual STEP 3 - Email Input	team_members.email	User says "Do it manually"
	"Select role for each member"	Manual STEP 3 - Role Dropdown	team_members.role	User unclear on roles
STEP 3 Channels	"Let's connect your channels! Select from grid"	Manual STEP 5 - Channel Grid	channels.channelType	User says "Configure manually"
STEP 3 Channels	"Configure now or use defaults?"	Manual STEP 5 - Per-Channel Settings	channels.configuration JSONB	User says "Configure now"
STEP 4 Fall-Back Logic	"What if no one replies to a customer?"	Manual STEP 6 - Escalation Rules	escalation_rules table	User says "Set up manually"
STEP 4 Fall-Back Logic	"Send follow-up after delay?"	Manual STEP 6 - Follow-Up Triggers	follow_up_rules table	User says "Skip"
STEP 5 AI Assistant	"Single or multiple AI assistants?"	Manual STEP 4 - AI Creation	ai_assistants table	User says "Configure manually"
STEP 5 AI Assistant	"AI name, tone, personality?"	Manual STEP 4 - AI Settings	ai_assistants.name/tone/personality	User says "Skip"
STEP 6 Automation	"Create starter automation?"	Manual STEP 8 - Template Library	automation_templates	User says "No, skip"
STEP 6 Automation	"Select template category"	Manual STEP 8 - Category Filter	user_automations.templateId	User says "Browse manually"

🔄 Fallback Workflow (Detailed)

💬

Copilot Asks

Beezaro: "What's your business name?"

→

🚫

User Says No

User: "No" or "Skip"

→

📝

Opens Manual

Redirect to STEP 2 screen

↓

✅

User Completes

Enters "GreenLeaf Pharmacy"
Saves to DB

→

🔙

Returns to Chat

Clicks "Return to Beezaro"
Resumes from next question

🌐 BEEZARO REAL-TIME COMMUNICATION (WebSocket)

♻️ Reuses Existing Socket.IO Infrastructure

Beezaro leverages the same Socket.IO + Redis Pub/Sub infrastructure documented in Manual Onboarding STEP 6.

Reference: See ADDENDUM_OPERATIONAL_ARCHITECTURE_DECISIONS.md → Decision #22: WebSocket Scaling

📡 Beezaro-Specific Socket.IO Events

🔌 WebSocket Event Specifications

Event 1: copilot:message:send (Client → Server)

Triggered: User types message and clicks send
Payload:

{
  sessionId: "uuid-...",
  message: "GreenLeaf Pharmacy",
  timestamp: "2025-10-22T10:30:45Z"
}

Server Action:
1. Save message to copilot_conversation_history
2. Process with OpenAI (extract intent + data)
3. Generate Beezaro response
4. Emit copilot:message:receive

Event 2: copilot:message:receive (Server → Client)

Triggered: After processing user message
Payload:

{
  sessionId: "uuid-...",
  beezaroMessage: "Great! Your business name is GreenLeaf Pharmacy. Next question...",
  messageType: "beezaro",
  stepContext: "business_identity",
  nextAction: "ask_industry",
  timestamp: "2025-10-22T10:30:47Z"
}

Client Action: Display Beezaro message in chat

Event 3: copilot:typing (Server → Client)

Triggered: While OpenAI is processing
Payload:

{
  sessionId: "uuid-...",
  isTyping: true
}

Client Action: Show "Beezaro is typing..." indicator with animated dots

Event 4: copilot:step:complete (Server → Client)

Triggered: When a step is marked complete
Payload:

{
  sessionId: "uuid-...",
  completedStep: "business_identity",
  nextStep: "team_members",
  progressPercentage: 17 // (1/6 steps done)
}

Client Action: Update progress stepper visual (checkmark on completed step)

Event 5: copilot:fallback:trigger (Server → Client)

Triggered: When user says "No" or validation fails
Payload:

{
  sessionId: "uuid-...",
  reason: "user_said_no",
  fromStep: "business_identity",
  manualScreenUrl: "/onboarding/manual/step-2/business-name",
  returnToken: "token-for-return" // Used to resume copilot later
}

Client Action: Redirect to manual screen URL with return token in query params

🔧 Connection Management

Copilot Session Lifecycle

1. Connection Establishment:
• User clicks "Let Beezaro Set Everything Up For Me"
• Frontend establishes WebSocket connection
• Backend creates copilot_sessions record
• Emit copilot:message:receive with welcome message

2. Active Conversation:
• User types → copilot:message:send
• Server shows copilot:typing while processing
• Server responds with copilot:message:receive
• Update copilot_sessions.lastActiveAt on every message

3. Idle Detection:
• Cron job checks lastActiveAt every 5 minutes
• If inactive > 30 minutes → Update status to 'paused'
• Send email: "You have an incomplete onboarding. Resume?"

4. Reconnection:
• User returns, clicks "Continue Onboarding"
• Load copilot_sessions by sessionId
• Load copilot_conversation_history (last 10 messages)
• Resume from currentStep

☁️ BEEZARO AWS INFRASTRUCTURE (Reuses Existing)

♻️ No New Infrastructure Required

Beezaro leverages 100% of the existing AWS infrastructure documented in the Manual Onboarding sections.

Key Point: Copilot is a different UI/UX layer on top of the same backend services and infrastructure. No additional AWS resources needed.

☁️ AWS Components Reused

AWS Service	How Beezaro Uses It	Changes Needed
ECS Fargate	Hosts NestJS backend (including Beezaro services)	✅ None - Same containers
RDS PostgreSQL	Stores 4 new Beezaro tables + existing tables	⚠️ Add 4 tables via migration
ElastiCache Redis	Cache conversation context (5-min TTL) + Socket.IO pub/sub	✅ None - Same instance
S3	Store uploaded logos & knowledge base files (same as manual)	✅ None - Same buckets
API Gateway	Route copilot API calls (/api/copilot/*)	✅ None - Auto-configured
CloudWatch	Monitor copilot sessions, message latency, fallback triggers	⚠️ Add copilot-specific metrics
Secrets Manager	Store OpenAI API key	⚠️ Add 1 new secret (OpenAI)
Lambda	Cleanup abandoned sessions (cron job)	⚠️ Add 1 new Lambda function

🧠 OpenAI API Integration (New)

🤖 OpenAI GPT-4 Configuration

API Specification:

• Model: gpt-4-turbo-preview (128K context window)
• Endpoint: https://api.openai.com/v1/chat/completions
• Authentication: Bearer token (from AWS Secrets Manager)
• Rate Limit: 10,000 requests/day (OpenAI tier 2)
• Timeout: 30 seconds max per request

Cost Estimation:

Per Conversation:
• Average messages per onboarding: 20 messages
• Input tokens per message: ~500 tokens (context + question)
• Output tokens per message: ~200 tokens (Beezaro response)
• Total tokens per onboarding: (500 + 200) × 20 = 14,000 tokens
• Cost per onboarding: $0.14 (at $0.01/1K input + $0.03/1K output)

Monthly Cost (Year 1):
• Estimated copilot users: 200/month (50% adoption)
• Monthly OpenAI cost: 200 × $0.14 = $28/month
• Annual cost: $336/year

At Scale (Year 3):
• 2,000 copilot users/month
• Monthly cost: $280/month = $3,360/year

Secrets Management:

• Store in AWS Secrets Manager: unifiedbeez/openai/api-key
• Rotation: Manual (on key compromise)
• Access: ECS task role only

⚡ Lambda: Abandoned Session Cleanup

🧹 Session Cleanup Lambda

Function Purpose:

Detect and handle abandoned copilot sessions (users who started but didn't finish)

Trigger:

• Schedule: EventBridge cron (every 5 minutes)
• Query: Find copilot_sessions WHERE status='active' AND lastActiveAt < NOW() - 30 minutes

Actions:

1. Update copilot_sessions.status = 'paused'
2. Send email notification: "You have an incomplete onboarding. Resume here: [link]"
3. Log to CloudWatch for analytics

Cost:

• Runtime: Node.js 18
• Memory: 128MB
• Avg execution time: 2 seconds
• Invocations/month: 8,640 (every 5 min)
• Cost: ~$0.20/month (within free tier)

🛡️ GDPR COMPLIANCE (Applies to BOTH Manual & Beezaro)

✅ Shared GDPR Compliance Across Both Onboarding Modes

Important: Beezaro Copilot collects the same data as Manual Onboarding, just through a conversational interface instead of forms. Therefore, ALL GDPR compliance measures documented in Manual Onboarding (Frame 9) apply equally to Beezaro Copilot.

📋 GDPR Articles Compliance Summary

GDPR Article	Compliance Status	Beezaro-Specific Implementation
Article 6: Lawful Basis	✅ Compliant	Conversation history collected for service delivery Retention: Chat logs stored for 90 days in copilot_conversation_history
Article 7: Consent	✅ Compliant	User chooses "Let Beezaro Set Everything Up For Me" in STEP 0 Explicit consent to conversational data collection
Article 13: Right to Information	✅ Compliant	Beezaro intro modal explains: "I'll set everything up for you in just a few questions" User can exit to manual at any time (transparency) Settings banner: "You're in control. All settings can be changed anytime in your dashboard."
Article 15: Right of Access	✅ Compliant	API: GET /api/copilot/conversation/:sessionId - Full chat history export Summary screen shows all collected data before confirmation User can download conversation transcript (JSON/CSV)
Article 16: Right to Rectification	✅ Compliant	Summary screen has edit icons for ALL collected data User can "Go back" and modify any response Real-time correction during chat or post-setup in dashboard
Article 17: Right to Erasure	✅ Compliant	Copilot sessions can be deleted: DELETE /api/copilot/session/:sessionId Conversation history cascade-deleted when session deleted Organization deletion removes all copilot data Fallback triggers auto-deleted after 1 year
Article 22: Automated Decision-Making	✅ Compliant	AI provides suggestions only (not decisions) User explicitly confirms all settings in summary screen Can switch to manual setup at any point No automated legal/financial decisions made
Article 25: Data Protection by Design	✅ Compliant	Minimal data collection (only what's needed for setup) No full message content in logs (metadata only) OpenAI API calls use ephemeral context (not stored) Privacy-first architecture
Article 28: Data Processors	✅ Compliant	OpenAI: DPA signed, GDPR-compliant, data not used for training AWS: GDPR-compliant infrastructure (RDS, S3, ECS) All processors have Data Processing Agreements
Article 32: Security Measures	✅ Compliant	TLS 1.3 encryption for all chat communications OpenAI API key in AWS Secrets Manager WebSocket connections secured (wss://) Rate limiting prevents abuse Same security as Manual Onboarding + OpenAI security

🔄 Data Synchronization & GDPR:
When user switches between Beezaro and Manual (via fallback):

Data collected in chat is saved to same tables as manual forms
GDPR rights apply to all collected data regardless of collection method
User data export includes both chat transcripts and form submissions
Deletion requests remove data from both copilot_* and main tables

📚 Complete GDPR Documentation:
For full implementation details, see:

Manual Onboarding Frame 9: Complete GDPR compliance (7 articles)
COMPLETE_GDPR_COMPLIANCE_GUIDE.md: 1,088-line comprehensive guide
Both onboarding modes follow identical compliance measures

🎯 Key Takeaway:

Beezaro Copilot does NOT introduce new GDPR requirements. It collects the same data as Manual Onboarding through a different interface. All existing GDPR compliance measures (Article 6, 7, 13, 15, 16, 17, 22, 25, 28, 32) apply identically to both modes. The only addition is OpenAI as a data processor (Article 28), which has a signed DPA.

Beezaro Copilot - Conversational Onboarding Architecture

📋 See Also: Manual Onboarding

🎯 What is Beezaro Copilot?

📝 MANUAL ONBOARDING

🤖 BEEZARO COPILOT

🔄 CRITICAL FALLBACK LOGIC (When User Says "No")

🚀 STEP 0 & 0.5: Entry Points (Critical Fallback Opportunities)

STEP 0: Welcome & Mode Selection

STEP 0.5: Beezaro Intro Modal

📋 Beezaro Onboarding Steps (6 Main Steps)

Business Identity

Team Members

Channels

Escalation Rules

AI Assistant

Automation

🎨 Beezaro UI Components (From 226 UI Screens)

Core Components

Device Variants

🎛️ Command Bar (Advanced Settings - Post-Onboarding)

💬 Beezaro Conversational Service

📊 Onboarding State Management Service

🧠 AI Response Generation Service

📊 COMPLETE STEP MAPPING

🔄 Fallback Workflow (Detailed)

♻️ Reuses Existing Socket.IO Infrastructure

📡 Beezaro-Specific Socket.IO Events

🔌 WebSocket Event Specifications

🔧 Connection Management

♻️ No New Infrastructure Required

☁️ AWS Components Reused

🧠 OpenAI API Integration (New)

🤖 OpenAI GPT-4 Configuration

⚡ Lambda: Abandoned Session Cleanup

🧹 Session Cleanup Lambda

🛡️ GDPR COMPLIANCE (Applies to BOTH Manual & Beezaro)

✅ Shared GDPR Compliance Across Both Onboarding Modes

📋 GDPR Articles Compliance Summary