ARCHITECTURE.md

🏗️ TechStore Support Agent - Architecture Guide

Project Overview

This is an AI-powered customer support chatbot that uses LangGraph (ReAct pattern) and HuggingFace models to answer customer questions about TechStore products and services.

Goal: Automate customer support by intelligently routing questions to the right tools and providing instant answers.

---

How It Works: The ReAct Loop

Step 1: User Sends Message

User: "What is your return policy?"
         ↓
    Flask Backend (/api/chat)
         ↓
    Creates LangGraph session

Step 2: Agent Thinks

The Qwen AI Model receives the question and decides:

• "I need to search the FAQ for 'return policy'"
• Outputs in this format:

  Thought: The user is asking about return policy
  Action: search_faq
  Action Input: {"query": "return policy"}
  

Step 3: Tool Execution

The agent's decision is parsed and a tool is executed:

search_faq("return policy")
→ Returns best matching FAQ entries
→ "You may return items within 30 days..."

Step 4: Agent Responds

The tool result is fed back to the AI, which writes:

Thought: I have the information needed
Final Answer: You may return most items within 30 days...

Step 5: Stream to User

Response is streamed via Server-Sent Events (SSE) in real-time:

Browser receives: "You may return most items within 30 days..."
Shows on screen instantly

---

Project Structure

langgraph-support-agent/
├── app.py                 # Main Flask server
├── events.py              # Event streaming system
├── requirements.txt       # Python dependencies
├── Dockerfile             # Container config
├── agent/
│   ├── __init__.py
│   ├── state.py          # Agent state definition
│   ├── tools.py          # 5 support tools
│   ├── llm.py            # Qwen integration
│   ├── nodes.py          # ReAct nodes
│   └── graph.py          # LangGraph definition
├── data/
│   └── faq.json          # FAQ knowledge base
├── templates/
│   └── index.html        # Web UI
├── static/
│   └── app.js            # Frontend logic
└── docs/
    └── project-template.html

---

The 5 Tools

1. 🔍 search_faq(query)

• What: Searches the FAQ knowledge base
• Use Case: User asks "What's your return policy?"
• Example:

  search_faq("return policy")
  → Returns matching FAQ entries
  

2. 📦 check_order_status(order_id)

• What: Looks up order status and tracking
• Use Case: User asks "Where is my order ORD-482910?"
• Example:

  check_order_status("ORD-482910")
  → Order: ORD-482910: Shipped. Tracking #1234567890. ETA: March 25, 2026
  

3. 🛍️ get_product_info(product_name)

• What: Returns product specs, price, availability
• Use Case: User asks "Do you have laptops in stock?"
• Example:

  get_product_info("laptop")
  → Product: ProBook X15
     Price: $1,299
     Availability: In Stock
     Specs: Intel i7-13th, 16GB RAM, 512GB NVMe SSD
  

4. 🎫 create_ticket(issue, priority)

• What: Creates a support ticket
• Use Case: User says "I need to report a broken product"
• Example:

  create_ticket("Screen is broken", "high")
  → Ticket TKT-ABC123 created
     Priority: HIGH
     Expected response: within 8 hours
  

5. 👤 escalate_to_human(reason)

• What: Transfers conversation to human agent
• Use Case: User says "I want to talk to someone"
• Example:

  escalate_to_human("Unhappy customer")
  → Escalation ESC-XYZ initiated
     Queue position: 3 | Est. wait: 15 minutes
  

---

Key Technologies

Component	Purpose
Flask	Web server & API
LangGraph	Agent orchestration (ReAct pattern)
Qwen 2.5 7B	AI Model (HuggingFace Inference API)
Server-Sent Events	Real-time streaming
Threading	Async task processing
LangChain	Message handling & parsing

---

The ReAct Pattern

ReAct = Reasoning + Acting

┌─────────────────────────────────────────┐
│  1. Router Node                         │
│     ↓                                   │
│  2. Agent Loop (Reasoning)              │
│     - Qwen thinks about question        │
│     - Decides which tool to use         │
│     ↓                                   │
│  3. Tool Executor (Acting)              │
│     - Executes the chosen tool          │
│     - Returns result                    │
│     ↓                                   │
│  4. Back to Agent (Loop)                │
│     - Has tool result                   │
│     - Decides: use another tool or end? │
│     ↓                                   │
│  5. Responder Node                      │
│     - Final answer sent to user         │
│     ↓                                   │
│  6. END                                 │
└─────────────────────────────────────────┘

Max 4 tool calls per turn (to prevent infinite loops)

---

UI Layout (60% Chat Focus)

┌─────────────────────────────────────────────────────┐
│ 🛍️ TechStore Support Agent  │ Orders · FAQs · Tickets │
├──────────────────────────────────────────────────────┤
│          │                              │            │
│          │                              │            │
│  20%     │         60% Chat             │   20%      │
│ Sidebar  │  (Messages & Input)          │  Panel     │
│          │                              │ (Tools &   │
│ • Model  │  User: "What is return      │  Trace)    │
│ • Status │         policy?"             │            │
│ • Stats  │                              │ • Tool     │
│          │  Agent: "You may return     │   Calls    │
│          │  items within 30 days..."   │ • Execution│
│          │                              │  Trace     │
│          │                              │            │
└──────────────────────────────────────────────────────┘

---

Data Flow

┌────────────┐
│   User     │
└──────┬─────┘
       │ "What is your return policy?"
       ↓
┌──────────────────────────────────┐
│   Flask API /api/chat            │
│   - Validates input              │
│   - Gets HF_TOKEN from .env      │
└──────┬───────────────────────────┘
       │
       ↓
┌──────────────────────────────────┐
│   LangGraph StateGraph           │
│   - Manages Agent State          │
│   - Orchestrates nodes           │
└──────┬───────────────────────────┘
       │
       ├─ Router Node → sends to Agent
       │
       ├─ Agent Node
       │   - Calls Qwen AI model
       │   - Parses: "Action: search_faq"
       │
       ├─ Tool Executor Node
       │   - Executes tool
       │   - search_faq("return policy")
       │
       ├─ Agent Node (again)
       │   - Decides: Final Answer or more tools?
       │
       └─ Responder Node
           - Finalizes response
           - Emits events via SSE
           │
           ↓
    ┌─────────────────────┐
    │  Browser (SSE)      │
    │  Receives events    │
    │  in real-time       │
    └─────────────────────┘
           │
           ↓
    ┌─────────────────────┐
    │  User sees answer   │
    │  "You may return... │
    └─────────────────────┘

---

How to Extend This

Add a New Tool

1. Create function in agent/tools.py:

   def my_tool(param: str) -> str:
       """My new tool."""
       return "result"
   

2. Add to TOOLS dict:

   TOOLS = {
       ...
       "my_tool": {"fn": my_tool, "desc": "My tool", "icon": "🔧"},
   }
   

3. Update system prompt in agent/llm.py to mention it

Change AI Model

Edit app.py:

AVAILABLE_MODELS = [
    {"id":"different-model/name","name":"Display Name","badge":"✓"},
]

Update FAQ

Edit data/faq.json - add/modify entries

---

Deployment

This is designed for HuggingFace Spaces:

1. Set HF_TOKEN in Space Secrets
2. Push code to repo
3. Space auto-deploys with Docker
4. Runs on port 7860

---

Summary

• What: Customer support chatbot for TechStore
• How: LangGraph orchestrates an AI agent through a ReAct loop
• Why: Automate support & provide instant answers
• Tech: Flask + LangGraph + Qwen + SSE streaming
• Scalable: Can add more tools/FAQs without changing architecture