VayzoMart Customer Support Chatbot — Architecture & Technical Reference (Phase 1)¶

Executive Summary¶

Phase 1 of the VayzoMart Customer Support Chatbot delivers a production-oriented, isolated customer-support module embedded within the existing monolithic ASP.NET Core backend and React/Vite customer and admin web applications.

The module provides: 1. Intelligent automated assistance using an approved VayzoMart Knowledge Base. 2. Read-only, customer-ownership-verified lookups for orders, shipments, returns, and refunds. 3. Structured intent classification and safe fallbacks with zero hallucinations. 4. Seamless human-agent handoff preserving complete transcript context. 5. Admin/Staff support console with queue management, assignment, replies, and status transitions. 6. Accessible customer floating chat widget with live polling.

High-Level Architecture¶

flowchart TD
    subgraph CustomerWeb [Customer Web Frontend]
        Widget[CustomerSupportWidget.jsx] -->|HTTP / REST + Polling| SupportCtrl[CustomerSupportController]
    end

    subgraph AdminWeb [Admin Web Frontend]
        Queue[AdminSupportQueue.jsx] -->|HTTP / REST| AdminCtrl[AdminCustomerSupportController]
        Detail[AdminConversationDetail.jsx] -->|HTTP / REST + Polling| AdminCtrl
    end

    subgraph BackendAPI [ASP.NET Core Backend API]
        SupportCtrl -->|MediatR| SupportHandlers[Customer Support Handlers]
        AdminCtrl -->|MediatR| SupportHandlers
    end

    subgraph CustomerSupportModule [Isolated CustomerSupport Module]
        SupportHandlers --> AiAbstraction[ISupportAiService]
        SupportHandlers --> SupportDataService[ISupportDataService]
        SupportHandlers --> ConvRepo[ISupportConversationRepository]
        SupportHandlers --> TicketRepo[ISupportTicketRepository]
        SupportHandlers --> KnowledgeRepo[ISupportKnowledgeRepository]

        AiAbstraction --> RuleAi[RuleBasedSupportAiService]
        AiAbstraction -.-> LlmAi[ConfigurableLlmSupportAiService]
    end

    subgraph ExistingDomainServices [Existing Domain Repositories (Read-Only)]
        SupportDataService -->|Strict Ownership Verification| OrderRepo[IOrderRepository]
        SupportDataService -->|Strict Ownership Verification| LogisticsRepo[ILogisticsRepository]
        SupportDataService -->|Strict Ownership Verification| ReturnsRepo[IReturnsRepository]
        SupportDataService -->|Direct Read Query| RefundDb[RazorpayRefundAttempt]
    end

    subgraph Storage [Database (MySQL / SQLite)]
        ConvRepo --> DB[(SupportConversations & SupportMessages)]
        TicketRepo --> DB[(SupportTickets)]
        KnowledgeRepo --> DB[(SupportKnowledgeArticles)]
    end

Conversation Lifecycle & State Machine¶

stateDiagram-v2
    [*] --> BotActive: Customer opens chat / creates conversation

    state BotActive {
        [*] --> Greeting
        Greeting --> FAQ_Lookup: User asks policy/FAQ question
        Greeting --> Order_Lookup: User asks for order/shipment/refund
        Greeting --> Safe_Fallback: Unknown query (verified info missing)
    }

    BotActive --> WaitingForAgent: Customer clicks "Talk with agent" or asks for human
    WaitingForAgent --> AgentAssigned: Staff agent claims ticket ("Assign to Me")
    AgentAssigned --> AgentAssigned: Customer & Agent exchange messages
    AgentAssigned --> Resolved: Agent marks inquiry Resolved
    Resolved --> Closed: Inactive / Customer or Admin closes
    WaitingForAgent --> Closed: Inactive / Customer or Admin closes
    Closed --> [*]

State Definitions¶

State	Code	Description
`BotActive`	`0`	Automated bot handles messages using knowledge articles and read-only order projections.
`WaitingForAgent`	`1`	Customer requested human assistance. Queued for staff review. Bot auto-responses paused.
`AgentAssigned`	`2`	A staff member assigned the conversation to themselves. Direct human-to-customer chat.
`Resolved`	`3`	Support issue was addressed and verified.
`Closed`	`4`	Terminal state. Conversation is read-only; new customer messages cannot be added.

Data Model & Schema¶

Four primary entities represent the Customer Support module:

erDiagram
    SupportConversation ||--o{ SupportMessage : contains
    SupportConversation ||--o| SupportTicket : links
    User ||--o{ SupportConversation : initiates
    User ||--o{ SupportTicket : creates
    User ||--o{ SupportConversation : assigned_to

    SupportConversation {
        uuid Id PK
        uuid CustomerUserId FK
        string Channel
        string Status
        string Priority
        uuid AssignedAgentId FK
        string Subject
        datetime ClosedAt
        datetime CreatedAt
        datetime UpdatedAt
        boolean IsDeleted
    }

    SupportMessage {
        uuid Id PK
        uuid ConversationId FK
        string SenderType
        uuid SenderUserId FK
        text Message
        string Intent
        text MetadataJson
        datetime CreatedAt
        datetime UpdatedAt
        boolean IsDeleted
    }

    SupportTicket {
        uuid Id PK
        string TicketNumber UK
        uuid ConversationId FK
        uuid UserId FK
        uuid OrderId FK
        string Category
        string Priority
        string Status
        string Subject
        text Description
        text Resolution
        uuid AssignedAgentId FK
        datetime ClosedAt
        datetime CreatedAt
        datetime UpdatedAt
        boolean IsDeleted
    }

    SupportKnowledgeArticle {
        uuid Id PK
        string Category
        string Title
        text Content
        string Keywords
        int Version
        boolean IsActive
        datetime EffectiveFrom
        datetime CreatedAt
        datetime UpdatedAt
        boolean IsDeleted
    }

Tables & Indexes¶

SupportConversations:
Primary Key: Id (UUID)
Indexes: CustomerUserId, Status, AssignedAgentId, CreatedAt, (Status, CreatedAt), (CustomerUserId, Status)
Soft Delete: Query filter !IsDeleted
SupportMessages:
Primary Key: Id (UUID)
Indexes: ConversationId, CreatedAt, (ConversationId, CreatedAt)
Soft Delete: Query filter !IsDeleted
SupportTickets:
Primary Key: Id (UUID)
Unique Index: TicketNumber (TKT-YYYYMMDD-XXXX)
Indexes: UserId, OrderId, ConversationId, Status, Category, CreatedAt, (UserId, Status)
Soft Delete: Query filter !IsDeleted
SupportKnowledgeArticles:
Primary Key: Id (UUID)
Indexes: Category, IsActive, Title, (Category, IsActive)
Soft Delete: Query filter !IsDeleted

Structured Support Intents¶

The chatbot classifies incoming customer inquiries into structured SupportIntent categories:

Intent	Key Detection Keywords / Patterns	Action Taken
`OrderStatus`	order, track, status, where is my order, ORD-	Checks recent orders or specific order number for caller.
`ShipmentStatus`	shipping, courier, track, delivery, dispatched, awb	Checks tracking number, courier, and status.
`RefundStatus`	refund, money back, credited, refund status	Checks refund transaction and Razorpay gateway attempt.
`ReturnStatus`	return status, return request, return progress	Retrieves return request status.
`ReturnEligibility`	how to return, can i return, return policy	Evaluates return window and return guidelines.
`PaymentProblem`	payment failed, charged but not confirmed, deducted	Explains payment verification and reconciliation steps.
`DeliveryProblem`	delayed, late, not received, wrong address	Details delivery timeline estimates and escalation.
`DamagedProduct`	damaged, broken, defective, crushed	Prompts ticket creation / return request with photo evidence.
`AccountHelp`	password, login, email, phone, profile	Guides customer through self-service profile controls.
`SellerHelp`	sell on vayzomart, seller onboarding	Explains seller registration and portal navigation.
`PolicyQuestion`	terms, policy, privacy, warranty	Answers from verified knowledge articles.
`CreateTicket`	create ticket, open ticket, raise ticket	Creates a formal `SupportTicket`.
`RequestAgent`	talk to human, live agent, representative, speak to person	Escalates conversation to `WaitingForAgent`.
`GeneralFaq`	hello, hi, help, questions	Welcoming greeting and prompt for details.
`Unknown`	unrecognized or unverified queries	Safe fallback: "I don't have enough verified information to answer that. I can connect you with support."

AI Abstraction & Tool Safety Boundaries¶

Provider-Neutral Architecture (`ISupportAiService`)¶

All AI integration is abstracted behind ISupportAiService: - ClassifyIntentAsync(message, context, ct) - GenerateResponseAsync(prompt, ct)

The application provides two implementations: 1. RuleBasedSupportAiService: Deterministic, zero-cost, zero-latency rule-based classifier and template engine. Highly resilient, offline-capable, and completely immune to hallucinations or prompt injection. 2. ConfigurableLlmSupportAiService: Config-driven OpenAI / Azure OpenAI / Anthropic bridge with configurable API key injection, temperature, and fallback to RuleBasedSupportAiService on timeout or failure.

Strict Tool Execution Boundaries¶

The chatbot AI layer is strictly prohibitive: - ❌ NO direct DbContext access. - ❌ NO arbitrary SQL execution. - ❌ NO HTTP requests to external endpoints. - ❌ NO generic reflection-based action execution. - ❌ NO autonomous cancellations, refunds, payment captures, inventory adjustments, or return approvals. - ❌ NO trust in caller-supplied order IDs without ownership verification.

All read operations route through ISupportDataService, which guarantees:

// Strict ownership boundary:
var order = await _orders.GetByOrderNumberAsync(orderNumber);
if (order == null || order.CustomerId != customerUserId)
    return null; // Reject forgery silently

Security, Privacy & Rate Limiting¶

Partitioned Rate Limiting:
support-chat policy configured with 20 requests per minute per authenticated user or IP address.
Message payloads strictly validated (MaxLength: 2000).
Conversation & Transcript Isolation:
Customer endpoints enforce conversation.CustomerUserId == currentUserId.
Customer B attempting to read Customer A's conversation receives 404 Not Found (zero data leakage).
Admin RBAC:
Admin support endpoints are protected by [RequirePermission(Permissions.CustomerSupport.View)] and [RequirePermission(Permissions.CustomerSupport.Manage)].
Data Sanitization:
Passwords, server connection strings, and Razorpay secrets are never exposed in prompt contexts or chat messages.

Admin Support Console¶

The Admin application includes a dedicated support area at /admin/support: 1. Queue View (AdminSupportQueue.jsx): - Status filters: All, Waiting for Agent, Agent Assigned, Resolved, Closed. - Auto-refreshes every 10 seconds. - Displays customer name, email, subject, priority, unread message count, and last message snippet. 2. Conversation Detail (AdminConversationDetail.jsx): - Complete transcript history with visual distinctions between Customer, Bot, Agent, and System messages. - One-click "Assign to Me" action. - Real-time agent reply form. - Status transitions ("Mark Resolved", "Close"). - Customer and linked order/ticket context sidebar.

Verification & Automated Tests¶

Comprehensive tests certify all Phase 1 capabilities: - Backend Tests (backend/tests/ECommerce.Tests/Application/CustomerSupportFlowTests.cs): - 17 unit and integration scenarios covering conversation creation, FAQ answers, order ownership checks, refund lookups, agent handoff, ticket linking, and secret protection. - Frontend Tests (frontend/src/customer-support-chat.test.js): - API endpoint contracts, accessibility labels, modal states, queue filters, assignment controls, and routing integration.