---
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.