{ "meta": { "project": "WhatsApp Ticketing System", "date": "2026-04-02", "prepared_by": "Generated by TestSprite; synced with PRD v2.2" }, "product_overview": "A self-hosted, real-time WhatsApp support platform that converts WhatsApp conversations into structured tickets and enables agents to respond from a web dashboard. The app supports multiple WhatsApp channels, role-based access, and sub-second real-time updates.", "core_goals": [ "Automatically create and manage support tickets from inbound WhatsApp messages", "Support multiple WhatsApp numbers (channels) with persistent Baileys sessions", "Deliver low-latency real-time updates (sub-second) via WebSockets", "Run fully on-premise via a single docker-compose command", "Provide a modern, polished React UI with role-based access (admin and user)", "Retain full message history and audit logs indefinitely for compliance" ], "features": [ { "name": "User Login", "description": "Authenticate users with email and password to receive a JWT and access protected parts of the app.", "user_flows": [ "Navigate to /login -> Enter email and password -> Submit login form -> Redirect to /", "Navigate to /login -> Enter email and password -> Submit login form -> See error on invalid credentials" ] }, { "name": "Dashboard", "description": "Overview hub showing KPIs, recent activity and channel statuses; entry point to ticket and channel workflows.", "user_flows": [ "Navigate to / -> See KPI cards and activity feed and channel status bar -> Open a ticket from the activity feed -> Navigate to /tickets/:id", "Navigate to / -> If not authenticated, Redirect to /login -> See login screen" ] }, { "name": "Ticket List", "description": "Browse and filter tickets across channels with real-time row updates and batch actions.", "user_flows": [ "Navigate to /tickets -> See list of tickets with real-time updates -> Apply filter by status -> See filtered results -> Open a ticket from the list -> Navigate to /tickets/:id", "Navigate to /tickets -> Apply an invalid date range filter -> See validation error or empty result set" ] }, { "name": "Ticket Detail (Chat UI)", "description": "View full ticket conversation, send outbound replies, and manage ticket metadata (status, priority, due date, assignment).", "user_flows": [ "Navigate to /tickets/:id -> See message history and ticket sidebar -> Type reply -> Submit reply -> See outbound message confirmation via real-time update", "Navigate to /tickets/:id -> Type reply -> Submit reply -> See send failure notification (message:sent failure)" ] }, { "name": "Contacts", "description": "Staff view and search contacts; open contact detail to see all linked tickets, link or unlink the contact to a company (WhatsApp contacts only), and open any ticket thread.", "user_flows": [ "Navigate to /contacts -> See contact cards -> Click a contact -> Land on /contacts/:id -> See ticket list with links -> Click a ticket -> Navigate to /tickets/:id", "Navigate to /contacts/:id -> Choose a company from dropdown -> Save link -> See updated company association (or clear with No company)", "Navigate to /contacts -> Search by phone, name, or substring -> See filtered cards" ] }, { "name": "Companies", "description": "Staff manage companies, linked WhatsApp contacts, portal users, and browse all company tickets in a dedicated column.", "user_flows": [ "Navigate to /companies -> Open a company -> See left column (name, linked contacts with links to /contacts/:id, channels, portal users) and right column Tickets (open and closed) -> Click a ticket -> /tickets/:id", "Navigate to /companies -> Create a new company -> See it in the list" ] }, { "name": "Web portal (company user)", "description": "Company-scoped users use Dashboard and Tickets only; messages post to portal tickets (not WhatsApp).", "user_flows": [ "Log in as company_user -> See reduced nav -> Open Tickets -> Start or continue conversation on ticket thread" ] }, { "name": "Channels and Channel Settings", "description": "View WhatsApp channels, perform onboarding/QR authentication, and edit per-channel onboarding and AI/template settings (admin access).", "user_flows": [ "Navigate to /channels -> Open channels list and see connection statuses -> Navigate to /channels/:id -> Toggle onboarding and AI options -> Edit template textareas -> Save changes -> See confirmation that changes persisted", "Navigate to /channels -> Navigate to /channels/:id -> Toggle onboarding option -> Save changes -> See validation error or save failure feedback" ] }, { "name": "Settings", "description": "Personal user settings such as theme preference and changing the current user's password.", "user_flows": [ "Navigate to /settings -> Toggle theme -> See UI theme change and persistence on reload", "Navigate to /settings -> Attempt to change password with incorrect current password -> See error indicating invalid current password" ] }, { "name": "Admin — User Management", "description": "Admin screens to list, create, and update user accounts and roles; manage account active state.", "user_flows": [ "Navigate to /admin/users -> See list of users with roles and status -> Create a new user with role selection -> Submit new user -> See new user in the list", "Navigate to /admin/users -> As non-admin, attempt to access the page -> See access denied or redirect to /login or dashboard" ] }, { "name": "Admin — Audit Log Viewer", "description": "Admin-only, queryable and paginated audit log of system and agent actions for compliance and review.", "user_flows": [ "Navigate to /admin/audit-logs -> See paginated audit log entries -> Apply filters (actor, action, date range) -> See filtered results", "Navigate to /admin/audit-logs -> As non-admin, attempt to access the page -> See access denied or redirect to /login or dashboard" ] } ], "code_summary": { "version": "2", "type": "frontend", "tech_stack": [ "TypeScript", "React 18", "Vite", "Tailwind CSS", "Shadcn-style UI components", "Axios", "React Router", "Zustand", "TanStack React Query" ], "routes": [ { "path": "/login", "file": "apps/frontend/src/pages/Login.tsx", "auth_required": false, "description": "Email and password login" }, { "path": "/", "file": "apps/frontend/src/pages/Dashboard.tsx", "auth_required": true, "description": "Dashboard home" }, { "path": "/tickets", "file": "apps/frontend/src/pages/Tickets.tsx", "auth_required": true, "description": "Ticket list with filters" }, { "path": "/tickets/:id", "file": "apps/frontend/src/pages/TicketDetail.tsx", "auth_required": true, "description": "Ticket conversation and sidebar" }, { "path": "/contacts", "file": "apps/frontend/src/pages/Contacts.tsx", "auth_required": true, "description": "Contacts list (staff)" }, { "path": "/contacts/:id", "file": "apps/frontend/src/pages/ContactDetail.tsx", "auth_required": true, "description": "Contact detail: company link, ticket history" }, { "path": "/companies", "file": "apps/frontend/src/pages/Companies.tsx", "auth_required": true, "description": "Companies list (staff)" }, { "path": "/companies/:id", "file": "apps/frontend/src/pages/CompanyDetail.tsx", "auth_required": true, "description": "Company detail with tickets column" }, { "path": "/channels", "file": "apps/frontend/src/pages/Channels.tsx", "auth_required": true, "description": "WhatsApp channels grid" }, { "path": "/channels/:id", "file": "apps/frontend/src/pages/ChannelDetail.tsx", "auth_required": true, "description": "Channel settings onboarding and AI" }, { "path": "/settings", "file": "apps/frontend/src/pages/Settings.tsx", "auth_required": true, "description": "User settings" }, { "path": "/admin/users", "file": "apps/frontend/src/pages/admin/Users.tsx", "auth_required": true, "description": "Admin user management" }, { "path": "/admin/audit-logs", "file": "apps/frontend/src/pages/admin/AuditLogs.tsx", "auth_required": true, "description": "Admin audit log viewer" } ], "features": [ { "name": "User Login", "description": "JWT login against Node API", "files": [ "apps/frontend/src/pages/Login.tsx", "apps/frontend/src/store/authStore.ts", "apps/frontend/src/lib/api.ts" ], "entry_route": "/login", "user_interactions": [ "Enter email and password", "Submit login form", "See error on invalid credentials", "Redirect to dashboard on success" ], "api_calls": [ { "method": "POST", "endpoint": "/api/v1/auth/login" } ], "auth_required": false }, { "name": "Channels and channel settings", "description": "View WhatsApp channels and edit per-channel onboarding and AI settings as admin", "files": [ "apps/frontend/src/pages/Channels.tsx", "apps/frontend/src/pages/ChannelDetail.tsx" ], "entry_route": "/channels", "user_interactions": [ "Open channels list", "Click a channel to open detail", "Toggle onboarding and AI options", "Edit template textareas and save" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/channels" }, { "method": "GET", "endpoint": "/api/v1/channels/:id" }, { "method": "PATCH", "endpoint": "/api/v1/channels/:id" } ], "auth_required": true }, { "name": "Contacts detail and company link", "description": "Contact detail page and PATCH company assignment", "files": [ "apps/frontend/src/pages/Contacts.tsx", "apps/frontend/src/pages/ContactDetail.tsx", "apps/api/src/routes/contacts.ts" ], "entry_route": "/contacts", "user_interactions": [ "Open contact from list", "View tickets for contact", "Select company and save or unlink" ], "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": "Companies and ticket sidebar", "description": "Company detail with linked contacts and tickets list", "files": [ "apps/frontend/src/pages/Companies.tsx", "apps/frontend/src/pages/CompanyDetail.tsx", "apps/api/src/routes/companies.ts" ], "entry_route": "/companies", "user_interactions": [ "Open company", "Browse tickets column", "Navigate to contact or ticket" ], "api_calls": [ { "method": "GET", "endpoint": "/api/v1/companies" }, { "method": "GET", "endpoint": "/api/v1/companies/:id" } ], "auth_required": true } ], "known_limitations": [ "Ticket list has no date-range filter in UI (TC008 may not apply).", "Regenerate TestSprite code summary after major route changes for best MCP alignment." ] } }