{ "meta": { "project": "WhatsApp Ticketing System", "date": "2026-05-11", "prepared_by": "Generated by TestSprite" }, "product_overview": "A self-hosted, real-time support platform for managing WhatsApp conversations as structured tickets. Agents and admins can log in, handle tickets, manage channels, contacts, companies, and knowledge content from a web dashboard.", "core_goals": [ "Authenticate staff users and route them to the dashboard", "Let agents view, filter, and manage support tickets in real time", "Enable agents to reply to tickets with text or media and update ticket status", "Manage WhatsApp and email channels from a central admin interface", "Organize and maintain contacts, companies, and linked customer records", "Create and edit knowledge base content for support operations", "Administer staff users, AI agents, and audit logs from protected screens", "Support public signup completion for new company portal users" ], "features": [ { "name": "Admin Login", "description": "Allows staff to sign in with email and password and access the authenticated dashboard.", "user_flows": [ "Navigate to /login -> Enter email address -> Enter password -> Submit the login form -> See the dashboard", "Navigate to /login -> Enter invalid credentials -> Submit the login form -> See an error message" ] }, { "name": "Dashboard Overview", "description": "Shows key ticket and channel metrics after login, along with recent ticket activity.", "user_flows": [ "Navigate to / -> View open ticket count, high priority count, due today count, and channels online count -> Review recent tickets", "Navigate to / -> Select a recent ticket -> Open the ticket detail view" ] }, { "name": "Ticket List and Filtering", "description": "Provides a searchable, filterable list of tickets for staff users.", "user_flows": [ "Navigate to /tickets -> View the ticket list -> Apply a status filter -> Apply a priority filter -> Apply a channel filter -> Search ticket content -> Open a ticket detail view", "Navigate to /tickets -> View the ticket list -> Select a ticket row -> Open the ticket detail view" ] }, { "name": "Ticket Detail and Reply", "description": "Displays the full conversation thread and lets staff manage ticket properties and send replies.", "user_flows": [ "Navigate to /tickets -> Select a ticket -> View the chat-style thread -> Type a text reply -> Send the reply -> See the message appear in the thread", "Navigate to /tickets -> Select a ticket -> View the chat-style thread -> Attach media files -> Send the message -> See the media message appear in the thread", "Navigate to /tickets -> Select a ticket -> Change the ticket priority -> Set a due date -> Toggle escalation status -> Close the ticket -> See the ticket status update", "Navigate to /tickets -> Select a closed ticket -> Type a reply -> Attempt to send the reply -> See validation prevent sending to a closed ticket" ] }, { "name": "Channel Management", "description": "Lets admins view channels, add new WhatsApp or email channels, reconnect disconnected channels, and delete channels.", "user_flows": [ "Navigate to /channels -> View the channel list and status badges", "Navigate to /channels -> Start adding a WhatsApp channel -> Enter channel name and phone number -> See the QR code for linking -> Complete pairing -> See the channel become connected", "Navigate to /channels -> Start adding an email channel -> Enter the channel name -> Create the channel -> See the new email channel in the list", "Navigate to /channels -> Select a disconnected channel -> Reconnect the channel -> See the channel status update", "Navigate to /channels -> Select a channel -> Delete the channel -> See it removed from the list" ] }, { "name": "Channel Settings", "description": "Allows admins to configure alerts, onboarding, AI behavior, and ticket-closing messages for a channel.", "user_flows": [ "Navigate to /channels -> Select a channel -> Edit the channel name and alert settings -> Update onboarding and AI configuration -> Save settings -> See the updated configuration persist", "Navigate to /channels -> Select a channel -> Disable or enable the ticket-closing message -> Save settings -> See the change persist" ] }, { "name": "Contact Management", "description": "Lets staff browse contacts, search by identity details, and link a contact to a company.", "user_flows": [ "Navigate to /contacts -> View the contact grid -> Search by name, phone number, or email -> Open a contact detail view", "Navigate to /contacts -> Open a contact detail view -> Select a company to link -> Save the link -> See the company association update", "Navigate to /contacts -> Open a contact detail view -> Review the contact's ticket history -> Open one of the tickets" ] }, { "name": "Company Management", "description": "Supports creating companies and managing company-level settings, portal users, and AI scope.", "user_flows": [ "Navigate to /companies -> View the company list -> Enter a company name -> Create the company -> See it appear in the list", "Navigate to /companies -> Open a company detail view -> Edit the company name -> Save changes -> See the updated name", "Navigate to /companies -> Open a company detail view -> Toggle AI autoreply -> Select knowledge modules -> Choose a default AI agent -> Save changes", "Navigate to /companies -> Open a company detail view -> Create a portal user with email, password, and display name -> See the new portal user listed" ] }, { "name": "Knowledge Base", "description": "Lets staff create, edit, and delete knowledge modules used for support content and AI scope.", "user_flows": [ "Navigate to /knowledge-base -> View the module list -> Create a new module -> Enter title, slug, group label, and markdown body -> Save the module -> See it appear in the list", "Navigate to /knowledge-base -> Open an existing module -> Edit module content -> Save changes -> See the updated module", "Navigate to /knowledge-base -> Open an existing module -> Delete the module -> See it removed from the list" ] }, { "name": "Settings and Profile", "description": "Provides user profile access, theme switching, OpenAI key management for admins, and password changes.", "user_flows": [ "Navigate to /settings -> View profile details -> Toggle between dark and light theme -> See the theme preference change", "Navigate to /settings -> Enter a new password with the current password -> Submit the change -> See the password update succeed", "Navigate to /settings -> Enter an OpenAI API key and base URL -> Save settings -> See the configuration persist" ] }, { "name": "User Management (Admin)", "description": "Allows admins to create, update, activate, and deactivate staff users.", "user_flows": [ "Navigate to /admin/users -> View the user list -> Create a new user with email, password, and role -> See the new user appear in the list", "Navigate to /admin/users -> Open a user entry -> Change the user's role -> Save changes -> See the role update", "Navigate to /admin/users -> Open a user entry -> Toggle active status -> Save changes -> See the user become inactive" ] }, { "name": "AI Agents (Admin)", "description": "Lets admins manage AI agent configurations, including provider, model, persona, and knowledge scope.", "user_flows": [ "Navigate to /admin/ai-agents -> View the agent list -> Create a new agent with provider, API key, model, and persona -> Select knowledge scope -> Save the agent", "Navigate to /admin/ai-agents -> Open an existing agent -> Edit agent details -> Save changes -> See the updated configuration", "Navigate to /admin/ai-agents -> Open an existing agent -> Delete the agent -> See it removed from the list" ] }, { "name": "Audit Logs (Admin)", "description": "Provides a read-only audit trail with filters and pagination for admin review.", "user_flows": [ "Navigate to /admin/audit-logs -> View audit log entries -> Filter by action type -> Filter by entity type -> Filter by date range -> Move between pages" ] }, { "name": "Signup Flow", "description": "Supports a public chat-based signup process for new company portal users, ending with password setup on the completion page.", "user_flows": [ "Navigate to /login -> Click the sign-up option -> Start the chat-based signup flow -> Enter name, email, company, and phone -> Complete the captcha if shown -> Receive the verification step", "Navigate to /signup/complete -> Open the signup completion page from the verification link -> Set a password -> Submit completion -> See the account become ready for dashboard access" ] } ], "code_summary": { "version": "2", "type": "frontend", "tech_stack": [ "TypeScript", "React 18", "Vite 5", "Tailwind CSS", "Zustand", "TanStack React Query", "Socket.IO Client", "Axios", "react-router-dom v6", "lucide-react", "date-fns", "Cloudflare Turnstile (captcha)" ], "routes": [ { "path": "/login", "file": "src/pages/Login.tsx", "auth_required": false, "description": "Email/password login form with signup chat dialog" }, { "path": "/signup/complete", "file": "src/pages/SignupComplete.tsx", "auth_required": false, "description": "Complete registration from email verification link — set password" }, { "path": "/", "file": "src/pages/Dashboard.tsx", "auth_required": true, "description": "KPI cards (open tickets, high priority, due today, channels online), recent tickets list, channel status" }, { "path": "/tickets", "file": "src/pages/Tickets.tsx", "auth_required": true, "description": "Filterable ticket list with status/priority/channel filters, real-time updates via WebSocket" }, { "path": "/tickets/:id", "file": "src/pages/TicketDetail.tsx", "auth_required": true, "description": "Chat-style ticket thread with text/media replies, priority/due date/escalation controls" }, { "path": "/contacts", "file": "src/pages/Contacts.tsx", "auth_required": true, "description": "Contact grid with search by phone/name/email" }, { "path": "/contacts/:id", "file": "src/pages/ContactDetail.tsx", "auth_required": true, "description": "Contact details, company link management, list of contact tickets" }, { "path": "/channels", "file": "src/pages/Channels.tsx", "auth_required": true, "description": "List WhatsApp/email/web-chat channels with status. Admin can add/reconnect/delete channels" }, { "path": "/channels/:id", "file": "src/pages/ChannelDetail.tsx", "auth_required": true, "description": "Channel settings — name, alerts, onboarding, AI config, ticket-closing message" }, { "path": "/companies", "file": "src/pages/Companies.tsx", "auth_required": true, "description": "List all companies with account codes, create new company form" }, { "path": "/companies/:id", "file": "src/pages/CompanyDetail.tsx", "auth_required": true, "description": "Company name edit, AI knowledge modules, autoreply toggle, default AI agent, portal user management" }, { "path": "/knowledge-base", "file": "src/pages/KnowledgeBaseList.tsx", "auth_required": true, "description": "List of all knowledge modules with create button" }, { "path": "/knowledge-base/:id", "file": "src/pages/KnowledgeModuleEdit.tsx", "auth_required": true, "description": "Edit module title, slug, group label, sort order, markdown body. Delete module" }, { "path": "/settings", "file": "src/pages/Settings.tsx", "auth_required": true, "description": "User profile, theme toggle, OpenAI key management (admin), password change" }, { "path": "/admin/users", "file": "src/pages/admin/Users.tsx", "auth_required": true, "description": "User management — list, create, toggle active/inactive, change role" }, { "path": "/admin/ai-agents", "file": "src/pages/admin/AiAgents.tsx", "auth_required": true, "description": "AI agent catalog — create/edit/delete with provider, model, persona, KB scope" }, { "path": "/admin/audit-logs", "file": "src/pages/admin/AuditLogs.tsx", "auth_required": true, "description": "Paginated audit log viewer with action/entity/date filters" } ], "features": [ { "name": "Admin Login", "description": "Login with email and password, get JWT token, redirect to Dashboard", "files": [ "src/pages/Login.tsx", "src/store/authStore.ts", "src/lib/api.ts" ], "entry_route": "/login", "user_interactions": [ "Fill email input field with admin@example.com", "Fill password input field with Admin123!", "Click Login button to submit", "See error toast on invalid credentials", "Redirected to Dashboard on success" ], "api_calls": [ { "method": "POST", "endpoint": "/api/v1/auth/login" } ], "auth_required": false }, { "name": "Dashboard Overview", "description": "View KPI cards and recent tickets after login", "files": [ "src/pages/Dashboard.tsx" ], "entry_route": "/", "user_interactions": [ "View open ticket count card", "View high priority ticket count", "View tickets due today", "View channels online count", "Click on a recent ticket to navigate to detail" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/tickets" }, { "method": "GET", "endpoint": "/api/v1/channels" } ], "auth_required": true }, { "name": "Ticket List and Filtering", "description": "Browse all tickets with status, priority, and channel filters", "files": [ "src/pages/Tickets.tsx" ], "entry_route": "/tickets", "user_interactions": [ "View list of tickets", "Filter by status (open/closed)", "Filter by priority", "Filter by channel", "Search by ticket content", "Click ticket row to open detail" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/tickets" }, { "method": "GET", "endpoint": "/api/v1/channels" } ], "auth_required": true }, { "name": "Ticket Detail and Reply", "description": "View ticket thread, send text/media replies, manage ticket properties", "files": [ "src/pages/TicketDetail.tsx", "src/pages/TicketDetail.js" ], "entry_route": "/tickets/:id", "user_interactions": [ "View message thread (chat-style bubbles)", "Type text reply in message input", "Click send button", "Attach file(s) for media reply", "Change ticket priority dropdown", "Set due date", "Toggle escalation flag", "Close ticket via status change", "View intake answers in sidebar" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/tickets/:id" }, { "method": "POST", "endpoint": "/api/v1/tickets/:id/messages" }, { "method": "PATCH", "endpoint": "/api/v1/tickets/:id" } ], "auth_required": true }, { "name": "Channel Management", "description": "View, add, reconnect, and delete WhatsApp/email channels", "files": [ "src/pages/Channels.tsx" ], "entry_route": "/channels", "user_interactions": [ "View list of channels with status badges", "Click Add WhatsApp Channel button", "Enter channel name and phone number in modal", "See QR code for WhatsApp linking", "Click Add Email Channel button", "Enter email channel name", "Click Reconnect on disconnected channel", "Click Delete to remove a channel" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/channels" }, { "method": "POST", "endpoint": "/api/v1/channels/init" }, { "method": "POST", "endpoint": "/api/v1/channels/email" }, { "method": "POST", "endpoint": "/api/v1/channels/:id/reconnect" }, { "method": "DELETE", "endpoint": "/api/v1/channels/:id" } ], "auth_required": true }, { "name": "Channel Settings", "description": "Configure channel alerts, onboarding, AI, and ticket-closing message", "files": [ "src/pages/ChannelDetail.tsx" ], "entry_route": "/channels/:id", "user_interactions": [ "Edit channel name", "Configure SMS/email alert settings", "Enable/disable onboarding flow", "Edit onboarding prompt templates", "Configure AI assistant (model, system prompt, KB text)", "Enable/disable ticket-closing message", "Save settings" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/channels/:id" }, { "method": "PATCH", "endpoint": "/api/v1/channels/:id" }, { "method": "GET", "endpoint": "/api/v1/settings/platform" }, { "method": "GET", "endpoint": "/api/v1/settings/openai/models" } ], "auth_required": true }, { "name": "Contact Management", "description": "View contacts, search, link to companies", "files": [ "src/pages/Contacts.tsx", "src/pages/ContactDetail.tsx" ], "entry_route": "/contacts", "user_interactions": [ "View contact grid", "Search contacts by phone/name/email", "Click contact to view detail", "Select company to link contact", "Save contact company link", "View contact ticket list" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/contacts" }, { "method": "GET", "endpoint": "/api/v1/contacts/:id" }, { "method": "PATCH", "endpoint": "/api/v1/contacts/:id" }, { "method": "GET", "endpoint": "/api/v1/companies" } ], "auth_required": true }, { "name": "Company Management", "description": "Create companies, manage portal users, enable AI autoreply", "files": [ "src/pages/Companies.tsx", "src/pages/CompanyDetail.tsx" ], "entry_route": "/companies", "user_interactions": [ "View company list", "Enter company name and create", "Click company to view detail", "Edit company name", "Toggle AI autoreply", "Select knowledge modules for company", "Set default AI agent", "Create portal user (email, password, display name)" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/companies" }, { "method": "POST", "endpoint": "/api/v1/companies" }, { "method": "GET", "endpoint": "/api/v1/companies/:id" }, { "method": "PATCH", "endpoint": "/api/v1/companies/:id" }, { "method": "POST", "endpoint": "/api/v1/companies/:id/users" }, { "method": "GET", "endpoint": "/api/v1/companies/:id/knowledge-modules" }, { "method": "PUT", "endpoint": "/api/v1/companies/:id/knowledge-modules" }, { "method": "PUT", "endpoint": "/api/v1/companies/:id/default-ai-agent" } ], "auth_required": true }, { "name": "Knowledge Base", "description": "Create, edit, and delete knowledge modules", "files": [ "src/pages/KnowledgeBaseList.tsx", "src/pages/KnowledgeModuleEdit.tsx" ], "entry_route": "/knowledge-base", "user_interactions": [ "View list of knowledge modules", "Click create new module", "Enter title, slug, group label, body markdown", "Save module", "Edit existing module", "Delete module" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/knowledge-modules" }, { "method": "POST", "endpoint": "/api/v1/knowledge-modules" }, { "method": "GET", "endpoint": "/api/v1/knowledge-modules/:id" }, { "method": "PATCH", "endpoint": "/api/v1/knowledge-modules/:id" }, { "method": "DELETE", "endpoint": "/api/v1/knowledge-modules/:id" } ], "auth_required": true }, { "name": "User Management (Admin)", "description": "Create, edit, and deactivate staff users", "files": [ "src/pages/admin/Users.tsx" ], "entry_route": "/admin/users", "user_interactions": [ "View user list", "Click create user button", "Enter email, password, role in modal", "Optionally assign AI agent", "Toggle user active/inactive", "Change user role" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/users" }, { "method": "POST", "endpoint": "/api/v1/users" }, { "method": "PATCH", "endpoint": "/api/v1/users/:id" }, { "method": "GET", "endpoint": "/api/v1/ai-agents" } ], "auth_required": true }, { "name": "AI Agents (Admin)", "description": "Create, edit, delete AI agent configurations", "files": [ "src/pages/admin/AiAgents.tsx" ], "entry_route": "/admin/ai-agents", "user_interactions": [ "View list of AI agents", "Click create agent", "Enter display name, provider, API key, model, persona", "Select knowledge modules scope", "Preview available models from provider", "Edit existing agent", "Delete agent" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/ai-agents" }, { "method": "POST", "endpoint": "/api/v1/ai-agents" }, { "method": "PATCH", "endpoint": "/api/v1/ai-agents/:id" }, { "method": "DELETE", "endpoint": "/api/v1/ai-agents/:id" }, { "method": "POST", "endpoint": "/api/v1/ai-agents/preview-models" }, { "method": "GET", "endpoint": "/api/v1/knowledge-modules" } ], "auth_required": true }, { "name": "Audit Logs (Admin)", "description": "View paginated audit trail with filters", "files": [ "src/pages/admin/AuditLogs.tsx" ], "entry_route": "/admin/audit-logs", "user_interactions": [ "View audit log entries", "Filter by action type", "Filter by entity type", "Filter by date range", "Navigate pagination" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/audit-logs" } ], "auth_required": true }, { "name": "Settings and Profile", "description": "User profile, theme, OpenAI key, password change", "files": [ "src/pages/Settings.tsx" ], "entry_route": "/settings", "user_interactions": [ "View user profile (email, role)", "Toggle dark/light theme", "Enter OpenAI API key (admin only)", "Set OpenAI base URL", "List available OpenAI models", "Change password (current + new)" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/settings/platform" }, { "method": "PATCH", "endpoint": "/api/v1/settings/platform" }, { "method": "GET", "endpoint": "/api/v1/settings/openai/models" }, { "method": "PATCH", "endpoint": "/api/v1/users/:id" } ], "auth_required": true }, { "name": "Signup Flow", "description": "Public chat-based signup with email verification", "files": [ "src/pages/Login.tsx", "src/pages/SignupComplete.tsx" ], "entry_route": "/login", "user_interactions": [ "Click Sign up link on login page", "Chat with scripted bot (name, email, company, phone)", "Complete Turnstile captcha if configured", "Receive verification email", "Click verification link", "Set password on signup complete page", "Redirected to dashboard as company_user" ], "api_calls": [ { "method": "POST", "endpoint": "/api/v1/signup/chat" }, { "method": "GET", "endpoint": "/api/v1/signup/verify" }, { "method": "POST", "endpoint": "/api/v1/signup/complete" } ], "auth_required": false }, { "name": "Portal User Messaging", "description": "Company portal users send/receive messages on their company tickets", "files": [ "src/pages/Tickets.tsx", "src/pages/TicketDetail.tsx" ], "entry_route": "/tickets", "user_interactions": [ "View only own company tickets", "Click New Conversation button", "Type message and send", "Attach files to message", "View staff replies in real-time" ], "api_calls": [ { "method": "POST", "endpoint": "/api/v1/portal/messages" }, { "method": "GET", "endpoint": "/api/v1/tickets" } ], "auth_required": true } ], "known_limitations": [ { "issue": "WhatsApp QR pairing requires physical phone scan — cannot be fully automated in E2E tests", "location": "src/pages/Channels.tsx", "impact": "QR flow testing limited to verifying QR display and socket events" }, { "issue": "Email verification requires actual SMTP delivery — signup complete flow needs mock/test token", "location": "src/pages/SignupComplete.tsx", "impact": "Full signup E2E requires SMTP or test bypass" }, { "issue": "Cloudflare Turnstile captcha blocks automated testing when TURNSTILE_SECRET_KEY is set", "location": "src/pages/Login.tsx", "impact": "Signup tests may need captcha disabled in test environment" } ] } }