chatbot/todo.md

Homelegance Chatbot Full-Stack Upgrade

Phase 1: Backend Infrastructure

• Upgrade project to web-db-user (backend + database)
• Create database schema (conversations, messages, agents, workflow_nodes)
• Build API routes for chat, agents, and workflows
• Set up AI integration for chatbot responses

Phase 2: Agent Dashboard

• Build agent dashboard page with conversation list
• Real-time chat view for agents to monitor conversations
• Agent reply functionality
• Conversation status management (active, escalated, resolved)
• Agent metrics and stats

Phase 3: Workflow Designer

• Build visual drag-and-drop workflow canvas
• Node types: greeting, intent detection, response, condition, escalation
• Connection drawing between nodes
• Save/load workflow configurations
• Workflow preview/test mode

Phase 4: Integration & Testing

• Connect chatbot widget to real backend API
• Connect agent dashboard to live data
• Test full conversation flow (user → bot → escalation → agent)
• Verify workflow designer saves and loads correctly
• Write unit tests for backend API (14 tests passing)

Phase 5: Role-Based Access Control & User Management

• Add login restriction to Agent Dashboard (redirect unauthenticated users)
• Add login restriction to Workflow Designer (redirect unauthenticated users)
• Admin-only access to Workflow Designer (agents cannot see it)
• Build user management module in Agent Dashboard (admin can set user roles)
• Add admin-only backend procedures for user management
• Update navigation to show/hide links based on user role
• Optimize dashboard structure with sidebar navigation (DashboardLayout)
• Write unit tests for RBAC (31 new tests, 45 total passing)
• Add 'agent' role to user schema (admin, agent, user)
• agentProcedure middleware (requires agent or admin role)
• adminProcedure middleware (requires admin role only)
• Self-role-change prevention
• Role badges and access denied screens

Phase 6: Enhanced User Management

• Invitation system — send email invitations with unique invite links
• Invitation status tracking (pending, accepted, expired, revoked)
• Invitation table in database with token, email, role, status, expiry
• Invite acceptance flow — landing page to accept invite and create account
• Resend invitation functionality
• Revoke/cancel pending invitations
• Delete user with confirmation dialog and cascade handling
• User activity log (last login, invite date, role changes)
• Bulk actions (bulk delete, bulk role change)
• User search and advanced filtering (by role, status, date joined)
• Export users list to CSV
• User detail view / profile card
• Invitation history tab showing all sent invitations
• Backend API for all invitation CRUD operations
• Backend API for user deletion
• Write unit tests for invitation and deletion features (31 new tests, 76 total passing)

Phase 7: Login Page & Password Authentication

• Add passwordHash field to users table
• Add password_reset_tokens table to schema
• Build backend: register with email/password
• Build backend: login with email/password (session cookie)
• Build backend: forgot password (generate reset token)
• Build backend: reset password (validate token, update password)
• Create custom Login page with email/password form
• Add "Forgot your password?" link on login page
• Create Forgot Password page (enter email, receive reset link)
• Create Reset Password page (enter new password with token)
• Create Register page for new users
• Update routing: protect dashboard, workflow, user-management behind login
• Keep home page publicly accessible
• Update DashboardLayout to use custom auth instead of OAuth-only
• Write unit tests for login, register, forgot password, reset password (18 new tests, 94 total passing)

Phase 8: Conversation History Redesign & Bot Naming

• Add pagination to conversations API (limit, offset, total count)
• Add search by visitor name/email/message content
• Add filter by agent (who replied)
• Add filter by status (active, escalated, resolved, closed)
• Add filter by date range
• Add sort options (newest, oldest, most messages, last activity)
• Track assigned agent on conversations
• Redesign conversation list with compact card layout for large volumes
• Add conversation search bar with debounced input
• Add filter sidebar/toolbar with dropdowns
• Add pagination controls (page numbers, prev/next)
• Add conversation count and summary stats
• Add bulk actions for conversations (close, resolve, delete)
• Give AI bot a professional friendly name — Ellie
• Update bot name across chatbot widget, dashboard, and system prompt
• Write tests for new pagination and filtering API (20 new tests, 114 total passing)

Phase 9: Customer ID & Sales Rep in Conversation Table

• Add customerId field to conversations schema
• Add salesRep field to conversations schema
• Run database migration
• Update backend API to include Customer ID and Sales Rep in search and sort
• Update Agent Dashboard table with Customer ID and Sales Rep columns
• Display Customer ID and Sales Rep in chat panel header
• Add sort by Customer ID and Sales Rep
• Include Customer ID and Sales Rep in search
• Write tests for new sort options (116 total passing)

Phase 10: Agent Name Column & Customer Message Notifications

• Display assigned agent name in conversation table rows
• Add agent name column header with sorting
• Show agent name in chat panel header
• Implement browser push notifications when customer sends a message
• Add notification toggle button in dashboard header
• Add notification permission request UI
• Show in-app toast notification for new messages with "View" action button
• Write tests for agent name and sort features (119 total passing)

Phase 11: Workflow Designer Enhancements — Data, Guardrails & AI Suggestions

• Update greeting node to auto-detect customer ID from logged-in user session
• Add "Customer Data" node type — connects chatbot to customer account data (CRM lookup)
• Add "Sales Order" node type — connects chatbot to sales order data (order history, status)
• Add "Content Guardrail" node type — blocks sensitive questions (revenue, margin, internal data)
• Add configurable blocked topics list in guardrail node properties
• Add "AI Suggested" node type — auto-generated from frequently asked questions
• Build AI recommendation panel that analyzes FAQ patterns and suggests new nodes
• Implement approve/wait/decline moderation UI for AI-suggested nodes
• Approved nodes get added to the workflow canvas
• Declined nodes are removed from suggestions
• Waiting nodes stay in the queue for later review
• Update database schema to support new node types (workflow_suggestions table + expanded node type enum)
• Update backend to persist new node types and AI suggestion states (4 new endpoints)
• Write tests for new workflow features (133 total passing across 6 files)

Phase 12: Tidio-Inspired Enhancements — Flows, Playground, Analytics, Data Import

12a. Workflow Designer — Flow Categories & Sub-categories

• Reorganize Workflow Designer into tabbed categories: Support Flows, Leads Flows, Sales Flows, Others
• Support Flows sub-categories: Orders, Shipping, Returning, Cancelling, Deflect, Self Service
• Leads Flows sub-categories: Lead Capture, Qualify, Nurture
• Sales Flows sub-categories: Product Search, Recommendations, Dealer Locator
• Flow template gallery with preview cards per category (7 pre-built templates)
• Category sidebar with counts and sub-category drill-down

12b. Greeting Redesign — Button Options

• Redesign chatbot greeting with avatar, name, online status indicator (Tidio-inspired)
• Show "What can we help you with today?" greeting message
• Add quick-reply buttons: Orders, Shipping, Returning, Cancelling
• "Hit the buttons to respond" placeholder text
• Each button sends the corresponding message to start the flow

12c. Playground — Chatbot Testing

• Build Playground page accessible from sidebar navigation
• Interactive chatbot widget preview (simulates customer view)
• Test specific flows by selecting from flow list
• Show flow execution path in real-time during test
• Reset/restart test session button

12d. Analytics — Resolution Rate Tracking

• Build Analytics page with dashboard charts
• Track and display resolution rate (bot-resolved vs escalated)
• Interactions over time chart (bar chart)
• Average response time metrics
• Category breakdown (Orders/Shipping/Returning/Cancelling)
• Database schema for analytics_events table

12e. AI Agent Data Import Module (Lyro-inspired)

• Build Data Sources management page with tabbed UI (Sources / Connections / Templates)
• URL import — crawl website pages for FAQ/product data
• File upload — CSV/JSON import for bulk data
• Manual Q&A pairs entry
• API Connections — configure external API endpoints (sales orders, customer data)
• Connection testing and validation
• Action templates (Check Order Status, Track Shipment, Return Request, Cancel Order, Customer Lookup)
• Input/output variable mapping for API actions
• Database schema for data_sources and api_connections tables
• Write tests for all new features (144 total passing across 6 files)