100 lines
5.1 KiB
Markdown
100 lines
5.1 KiB
Markdown
---
|
|
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` |
|