83 lines
4.1 KiB
Markdown
83 lines
4.1 KiB
Markdown
---
|
|
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.
|