loyalty-agent-service/context-fe.md

trigger

trigger
always_on

Application Context: Frontend (React Chat UI)

Application Name: Loyalty Agent Chat UI
Module Path: Root directory (/, src/)
Runtime Port: 9333 (Vite Dev Server)
Technology Stack: React 19, Vite, TypeScript, Tailwind CSS, shadcn/ui components, Zustand, @stomp/stompjs, react-markdown, remark-gfm

---

1. Primary Roles & Responsibilities

The Frontend provides the user interface for the Loyalty Assistant Chatbot:

• Real-time Chat Experience: Maintains a WebSocket/STOMP connection with loyalty-agent (Port 9332), processing incoming token streams and displaying text dynamically.
• Tool Execution Status Indicator: Displays animated badges reflecting Agent tool invocations in real time (e.g., "Searching campaigns...", "Creating rule...").
• Rich Content Rendering: Renders Agent responses formatted with Markdown, tables, lists, and syntax-highlighted code blocks.
• Side Panel & Context Sync: Displays campaign lists and rule details side-by-side with the active chat window.

---

2. API & WebSocket Connectivity

Environment Variables & Connection Specs

• VITE_AGENT_HTTP_URL: HTTP base URL for Agent Service (Default: http://localhost:9332)
• VITE_AGENT_WS_URL: WebSocket URL for Agent Service (Default: ws://localhost:9332/ws)

State Management Flow (src/store/useChatStore.ts)

1. Connection Initialization: Establishes a STOMP client connection to ws://localhost:9332/ws.
2. Channel Subscription: Subscribes to /user/queue/chat-events.
3. Event Dispatching:
   • TOKEN: Appends incoming text tokens to streamingContent of the active Agent message.
   • TOOL_STATUS: Adds or updates tool execution badges in toolEvents for the active message bubble.
   • DONE: Concludes streaming (isStreaming = false), re-enabling user input.
   • ERROR: Displays error alerts directly in the chat stream.
4. Message Dispatch: Publishes JSON payload { content: string, conversationId: string } to /app/chat.

---

3. UI Component Architecture

src/
├── App.tsx                    # Root component
├── main.tsx                   # React DOM entry point
├── index.css / App.css        # Stylesheets & Tailwind directives
├── store/
│   └── useChatStore.ts        # Zustand store managing WebSocket STOMP, messages, sessions
├── services/                  # REST API Clients (Conversations, Campaigns)
├── components/
│   ├── ui/                    # Base UI Primitives (Button, Input, ScrollArea, Avatar, Card...)
│   └── chat/
│       ├── ChatLayout.tsx     # 3-column layout (Sidebar, Chat Window, Detail Panel)
│       ├── ChatList.tsx       # Chat message stream bubble list
│       ├── ChatBubble.tsx     # Message bubble with Markdown renderer & tool indicators
│       ├── ChatBottombar.tsx  # Message input bar & send button
│       ├── ChatHistoryList.tsx# Conversation history sidebar list
│       ├── WelcomeScreen.tsx  # Landing screen with initial prompt suggestions
│       └── ToolStatusIndicator.tsx # Animated tool execution badge

---

4. Auxiliary REST Endpoints

• Conversations:
  • GET /api/v1/conversations: Fetches conversation history.
  • GET /api/v1/conversations/{id}: Fetches message history for a specific conversation.
• Loyalty Campaign Proxies:
  • GET /api/v1/agent/campaigns: Fetches campaign list.
  • GET /api/v1/agent/campaigns/{campaignId}/rules: Fetches rules for a campaign.

---

5. Key Development Guidelines for Agents

1. Leverage Existing UI Primitives: Reuse primitives in src/components/ui/ and follow Tailwind CSS utility conventions.
2. Preserve STOMP Handling: Avoid modifying channel handlers in Zustand to prevent breaking /user/queue/chat-events or /app/chat.
3. Markdown Rendering Performance: Ensure ChatBubble and custom Markdown components handle high-frequency token streams smoothly without frame drops.
4. Responsive Design: Maintain clean 3-column layout responsiveness across varying viewport widths.