---
trigger: always_on
---

# Application Context: `loyalty-agent`

Application Name: **Loyalty Agent Service**  
Module Path: `loyalty-agent/`  
Runtime Port: `9332`  
Technology Stack: Java 25, Spring Boot 4.x, Spring AI 2.x, Spring WebSocket (STOMP), Ollama, Spring AI MCP Client

---

## 1. Primary Roles & Responsibilities

`loyalty-agent` acts as the **BFF (Backend-For-Frontend)** and **AI Orchestration Layer**:
- **BFF & WebSocket Server**: Manages WebSocket/STOMP connections with the Frontend (`src/`), receiving chat requests and streaming LLM responses back to the UI in real time.
- **AI Orchestrator**: Interacts with the Ollama LLM (`qwen3.5:4b`) via Spring AI `ChatClient`, routing user queries, managing prompt templates, and handling conversation state.
- **MCP Client**: Connects to `loyalty-mcp-server` via the MCP SSE protocol (`http://localhost:9331/sse`) to dynamically load and invoke loyalty business tools.
- **REST Proxy & Persistence**: Exposes REST endpoints to the Frontend for proxy data queries (Campaigns, Rules) and conversation history management.

---

## 2. Protocol & Real-time Chat Messaging Flow (WebSocket STOMP)

### WebSocket Configuration (`config/WebSocketConfig.java`)
- **STOMP Endpoint**: `/ws` (Supports SockJS fallback)
- **Application Destination Prefix**: `/app`
- **User Destination Prefix**: `/user`
- **Broker Prefixes**: `/topic`, `/queue`

### Messaging Flow
1. **Client Request**: Frontend sends a message to `/app/chat` with payload `{ content: string, conversationId: string }`.
2. **Server Processing**: `AgentController` receives the message and delegates it to `LoyaltyAgentService`, which processes it via Spring AI `ChatClient`.
3. **Event Streaming**: The server pushes events (`AgentEvent`) back to the client on `/user/queue/chat-events`.

### Event Types Sent to UI (`AgentEvent` Types)
- **`TOKEN`**: Text stream chunks returned in real time from the LLM. The UI appends these chunks sequentially for a typing effect.
- **`TOOL_STATUS`**: Status update when executing a tool (tool name, status `RUNNING` / `COMPLETED` / `FAILED`, arguments/results). The UI renders an animated indicator badge.
- **`DONE`**: Signals that the LLM has finished responding to the current request.
- **`ERROR`**: Signals system errors or failure during LLM/Tool execution.

---

## 3. AI & Environment Configuration (`application.yml` & `config/`)

- **Ollama LLM Provider**:
  - Base URL: `http://192.168.99.10:11434`
  - Model: `qwen3.5:4b`
- **MCP Server Connection**:
  - URL: `${MCP_SERVER_URL:http://localhost:9331/sse}`
  - Transport: SSE (Server-Sent Events)
- **Loyalty Core Integration**:
  - Base URL: `${LOYALTY_CORE_BASE_URL:http://192.168.99.242:8081}`
  - Authentication: Keycloak OAuth2 Client Credentials (`KEYCLOAK_TOKEN_URI`, `KEYCLOAK_CLIENT_SECRET`)

---

## 4. Source Code Architecture

```
dev.sonpx.loyalty.agent/
├── LoyaltyAgentApplication.java
├── config/
│   ├── AgentConfig.java          # RestClient & OAuth2 configuration for Core API
│   ├── WebSocketConfig.java      # STOMP WebSocket endpoints configuration
│   └── McpConfig.java            # Spring AI MCP Client setup
├── controller/
│   ├── AgentController.java      # STOMP @MessageMapping("/chat") & Proxy REST APIs
│   └── ConversationController.java # REST APIs for conversation history & messages
├── service/
│   ├── LoyaltyAgentService.java  # Core service building ChatClient & streaming LLM output
│   ├── AgentEventPublisher.java  # Helper to send AgentEvent via SimpMessagingTemplate
│   ├── ToolResultPresentationProcessor.java # Formats presentation content from tools
│   └── AgentPersistenceService.java         # Conversation & message persistence
└── core/
    ├── classifier/               # Intent classification logic
    ├── executor/                 # Plan and tool execution drivers
    ├── memory/                   # Conversation memory management
    ├── orchestrator/             # Agent execution flow coordination
    └── workflow/                 # Step-by-step workflow definitions
```

---

## 5. Key Development Guidelines for Agents

1. **Preserve STOMP Contract**: Do not alter `/app/chat` or `/user/queue/chat-events` unless coordinated with the Frontend.
2. **Propagate Conversation Context**: Ensure `conversationId` is passed consistently from WebSocket requests down to storage and MCP tool execution.
3. **Handle Presentation Content**: When tools return payload with `presentation.content`, ensure the processor preserves the raw Markdown for the LLM to present to the user.
4. **Ports & Env Vars**: Always target port `9332` for the Agent Service and respect standard environment variables for external endpoints.