---
trigger: always_on
---

# Project Context: Loyalty Agent Service

An AI Assistant system designed to manage and operate Loyalty business domain tasks (Campaigns, Rules, Point Pools, Tiers, and Members) for enterprise applications. The repository is structured as a monorepo containing 3 distinct applications communicating via WebSocket STOMP, HTTP REST APIs, and MCP SSE.

---

## 1. Architecture Overview

```
                     ┌──────────────────────────────────┐
                     │   Frontend (React 19 + Vite)     │
                     │   Port: 9333 (Dev Server)        │
                     └─────────────────┬────────────────┘
                                       │
                         WebSocket     │ REST Proxy
                         (STOMP /ws)   │ (/api/v1/agent/...)
                                       ▼
                     ┌──────────────────────────────────┐
                     │   `loyalty-agent` (Spring Boot)  │
                     │   Port: 9332 | BFF & AI Service  │
                     └─────────┬───────────────┬────────┘
                               │               │
                     Ollama    │               │ MCP SSE
              (qwen3.5:4b)     │               │ (http://localhost:9331/sse)
                               ▼               ▼
                 ┌──────────────────┐ ┌──────────────────────────────────┐
                 │ Ollama LLM Server│ │ `loyalty-mcp-server`             │
                 │ 192.168.99.10    │ │ Port: 9331 | MCP Tool Server     │
                 └──────────────────┘ └────────────────┬────────────────┘
                                                       │ OAuth2 Client Credentials
                                                       ▼
                                      ┌──────────────────────────────────┐
                                      │ Loyalty Core API (Spring Boot)   │
                                      │ 192.168.99.242:8081              │
                                      └──────────────────────────────────┘
```

---

## 2. Applications & Dedicated Context Files

Each application has a dedicated context file containing detailed architecture documentation, message contracts, and development guidelines:

1. **`loyalty-agent` (BFF & AI Orchestrator)**:
   - **Port**: `9332`
   - **Role**: Manages Ollama LLM interactions, STOMP WebSocket streaming to the UI, MCP Client execution, and conversation history.
   - **Detailed Specs**: [context-agent.md](./context-agent.md) (`@context-agent.md`)

2. **`loyalty-mcp-server` (MCP Tool Server)**:
   - **Port**: `9331`
   - **Role**: Exposes `@McpTool` endpoints for loyalty business domain operations (Campaigns, Rules, Pools), interacting with Loyalty Core API via OAuth2.
   - **Detailed Specs**: [context-mcp-server.md](./context-mcp-server.md) (`@context-mcp-server.md`)

3. **Frontend (React Chat UI)**:
   - **Port**: `9333`
   - **Role**: User interface for the AI Chatbot, handling STOMP stream events, rendering Markdown, displaying animated tool status badges, and rendering side panels.
   - **Detailed Specs**: [context-fe.md](./context-fe.md) (`@context-fe.md`)

---

## 3. Quick Startup & Commands

### Launch Entire Stack (Root Script)
```bash
./start-all.sh
```
*Automatically starts MCP Server (`9331`), Agent Service (`9332`), and Frontend (`9333`).*

### Manual Application Startup
```bash
# Terminal 1: MCP Server
./mvnw spring-boot:run -pl loyalty-mcp-server

# Terminal 2: Agent Service
./mvnw spring-boot:run -pl loyalty-agent

# Terminal 3: Frontend
pnpm dev
```

### Build & Test Commands
- **Frontend**: `pnpm install` | `pnpm lint` | `pnpm build`
- **Backend (Spring Boot)**: `./mvnw test` (Run all) | `./mvnw test -pl loyalty-agent` | `./mvnw test -pl loyalty-mcp-server`

---

## 4. Ports & Environment Variables Reference

| Component | Port | Default Endpoint | Key Environment Variables |
| :--- | :--- | :--- | :--- |
| **Frontend UI** | `9333` | `http://localhost:9333` | `VITE_AGENT_HTTP_URL`, `VITE_AGENT_WS_URL` |
| **Loyalty Agent** | `9332` | `http://localhost:9332`, `ws://localhost:9332/ws` | `MCP_SERVER_URL`, `LOYALTY_CORE_BASE_URL` |
| **Loyalty MCP Server** | `9331` | `http://localhost:9331/sse` | `KEYCLOAK_TOKEN_URI`, `KEYCLOAK_CLIENT_SECRET` |
| **Ollama LLM** | `11434` | `http://192.168.99.10:11434` | Defined in `loyalty-agent/application.yml` |
| **Loyalty Core API** | `8081` | `http://192.168.99.242:8081` | `LOYALTY_CORE_BASE_URL` |