# liyupi/yu-ai-agent architecture

> Architecture diagram of the GitHub repository liyupi/yu-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liyupi/yu-ai-agent
- Repository: https://github.com/liyupi/yu-ai-agent

## Overview

1. **Repository shape**
   - This repo is a small AI platform, not a single app: it contains a **Spring Boot backend**, a **Vue frontend**, and a separate **MCP image-search service**.
   - The backend is the orchestration layer; the frontend is just the chat/UI shell; the MCP server is an external tool endpoint the backend/agents can invoke.

2. **Backend runtime boundary**
   - `yu-ai-agent` is the main Java 21 / Spring Boot 3 service.
   - Its top-level responsibilities are exposed through `AiController` and `HealthController`, with cross-cutting config in `CorsConfig` and application settings in `application.yml` / `application-prod.yml`.
   - `YuAiAgentApplication` is the backend entrypoint.

3. **Two primary product flows in the backend**
   - The codebase centers on two user-facing capabilities:
     - **LoveApp**: an AI “恋爱大师” conversation assistant.
     - **YuManus**: a ReAct-style autonomous agent that plans and executes tasks.
   - These map to separate backend domains under `app/` and `agent/`, but they share the same AI and tool infrastructure.

4. **LoveApp architecture: chat + memory + knowledge**
   - `app/LoveApp` is the domain orchestration class for the romance assistant.
   - Conversation state is handled by `chatmemory/FileBasedChatMemory`, so memory is persisted outside process memory rather than being purely transient.
   - The assistant also has a RAG path under `rag/`, which loads and prepares the knowledge base from `src/main/resources/document/*.md`.

5. **RAG subsystem boundaries**
   - `LoveAppDocumentLoader`, `MyTokenTextSplitter`, `MyKeywordEnricher`, and `QueryRewriter` implement the document ETL / query-enrichment steps.
   - `LoveAppVectorStoreConfig` and `PgVectorVectorStoreConfig` define the vector-store integration; the project explicitly supports **PgVector** and cloud-based variants.
   - `LoveAppContextualQueryAugmenterFactory`, `LoveAppRagCloudAdvisorConfig`, and `LoveAppRagCustomAdvisorFactory` show that retrieval is wired into the Spring AI advisor pipeline rather than being a separate service.

6. **Agent subsystem**
   - `agent/BaseAgent`, `ReActAgent`, `ToolCallAgent`, and `YuManus` define a layered agent model.
   - `agent/model/AgentState` is the state container for iterative reasoning/execution.
   - This subsystem is the automation engine: it decides when to think, when to call tools, and when to stop.

7. **Tooling subsystem**
   - `tools/` contains the callable capabilities exposed to the AI model:
     - file operations
     - web search
     - web scraping
     - resource download
     - terminal execution
     - PDF generation
     - termination / control
   - `ToolRegistration` is the central place where those tools are made available to agents/models.
   - Architecturally, this is the main “actuation” boundary: the LLM does not directly touch the environment; it invokes these tools through the backend.

8. **MCP integration**
   - The backend has an MCP-oriented setup, and `src/main/resources/mcp-servers.json` indicates external MCP server configuration.
   - The separate `yu-image-search-mcp-server` module is a standalone Spring Boot service exposing `ImageSearchTool`.
   - It supports both `stdio` and `sse` modes via `application-stdio.yml` and `application-sse.yml`, so the image-search capability can be embedded or networked depending on deployment.

9. **Model/provider abstraction**
   - The repo is deliberately provider-agnostic at the architecture level.
   - The README and demo package show integration patterns for multiple model access modes: Spring AI, LangChain4j, HTTP calls, Ollama, and hosted APIs.
   - `demo/invoke/*` exists as a reference layer for comparing these access methods rather than as core runtime logic.

10. **Frontend boundary**
   - `yu-ai-agent-frontend` is a separate Vue 3 + Vite application.
   - Key views are `Home.vue`, `LoveMaster.vue`, and `SuperAgent.vue`, with a shared `ChatRoom.vue` component.
   - This frontend talks to the backend over HTTP; the presence of SSE in the README suggests some responses are streamed back asynchronously for chat/agent output.

11. **End-to-end data flow**
   - User enters the frontend chat UI.
   - Frontend calls backend controllers.
   - Backend routes the request into either LoveApp or YuManus.
   - LoveApp may consult file-based memory, run RAG retrieval over the knowledge documents/vector store, then call the LLM.
   - YuManus may iterate through reasoning steps, invoke tools, and optionally call MCP services.
   - Final text or streamed chunks are returned to the frontend.

12. **Persistence and data assets**
   - The main persistent assets visible in the repo are:
     - markdown knowledge documents under `src/main/resources/document`
     - file-based chat memory on disk
     - vector-store data in PgVector or cloud storage, depending on config
   - There is no traditional relational business domain in this repo; persistence is AI-state and knowledge oriented.

13. **Deployment packaging**
   - Each deployable has its own Dockerfile: backend, frontend, and MCP server.
   - This suggests a containerized, multi-service deployment where the frontend is served separately from the backend AI service, and the MCP service can be scaled or replaced independently.

14. **Testing and validation**
   - Tests are organized per subsystem: app, agent, RAG, tools, and the MCP server.
   - That mirrors the architecture: each major boundary has its own verification layer, which is useful when drawing the system diagram because the repo is modular rather than monolithic.

Main entry points: [`src/main/java/com/yupi/yuaiagent/controller/AiController.java`](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/controller/AiController.java) (HTTP API), [`src/main/java/com/yupi/yuaiagent/app/LoveApp.java`](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/app/LoveApp.java) (LoveApp), [`src/main/java/com/yupi/yuaiagent/agent/ReActAgent.java`](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/agent/ReActAgent.java) (Agent loop), [`src/main/java/com/yupi/yuaiagent/YuAiAgentApplication.java`](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/YuAiAgentApplication.java) (Spring Boot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend service"]
  node_backend_app["Spring Boot<br/>runtime"]
  node_backend_api["HTTP API<br/>controller<br/>[AiController.java]"]
  node_backend_health["Health API<br/>controller"]
  node_backend_config["Web config<br/>[CorsConfig.java]"]
  node_loveapp["LoveApp<br/>assistant domain<br/>[LoveApp.java]"]
  node_chat_memory[("File memory<br/>state store")]
  node_rag_loader["Doc loader<br/>rag ETL"]
  node_rag_transform["Query prep<br/>rag transform"]
  node_rag_store[("Vector store<br/>rag storage")]
  node_rag_advisor["RAG advisor<br/>advisor pipeline"]
  node_agent_core["YuManus<br/>agent runtime<br/>[YuManus.java]"]
  node_agent_loop["Agent loop<br/>reasoning loop<br/>[ReActAgent.java]"]
  node_agent_state["Agent state<br/>state model<br/>[AgentState.java]"]
  node_tools_reg["Tool registry<br/>tool boundary"]
  node_tools_suite["Tool suite<br/>tools<br/>[WebSearchTool.java]"]
  node_demo_invoke["Model demos<br/>reference layer"]
end

subgraph group_frontend["Frontend app"]
  node_frontend_app["Vue app<br/>runtime<br/>[App.vue]"]
  node_frontend_chat["Chat UI<br/>view<br/>[ChatRoom.vue]"]
  node_frontend_views["Product views<br/>view set<br/>[LoveMaster.vue]"]
end

subgraph group_mcp["MCP service"]
  node_mcp_app["MCP server<br/>runtime"]
  node_mcp_tool["Image search<br/>mcp tool"]
end

node_backend_app -->|"hosts"| node_backend_api
node_backend_app -->|"hosts"| node_backend_health
node_backend_app -->|"uses"| node_backend_config
node_backend_api -->|"routes chat"| node_loveapp
node_backend_api -->|"routes agent"| node_agent_core
node_loveapp -->|"persists state"| node_chat_memory
node_loveapp -->|"indexes docs"| node_rag_loader
node_rag_loader -->|"prepares"| node_rag_transform
node_rag_transform -->|"writes vectors"| node_rag_store
node_loveapp -->|"retrieves via"| node_rag_advisor
node_rag_advisor -->|"queries"| node_rag_store
node_agent_core -->|"drives"| node_agent_loop
node_agent_loop -->|"updates"| node_agent_state
node_agent_loop -->|"invokes"| node_tools_reg
node_tools_reg -->|"exposes"| node_tools_suite
node_agent_loop -->|"calls external MCP"| node_mcp_app
node_backend_api -.->|"served to"| node_frontend_app
node_frontend_app -->|"contains"| node_frontend_chat
node_frontend_app -->|"contains"| node_frontend_views
node_mcp_app -->|"hosts"| node_mcp_tool
node_demo_invoke -.->|"references"| node_backend_app

click node_backend_app "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/YuAiAgentApplication.java"
click node_backend_api "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/controller/AiController.java"
click node_backend_health "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/controller/HealthController.java"
click node_backend_config "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/config/CorsConfig.java"
click node_loveapp "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/app/LoveApp.java"
click node_chat_memory "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/chatmemory/FileBasedChatMemory.java"
click node_rag_loader "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/LoveAppDocumentLoader.java"
click node_rag_transform "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/MyTokenTextSplitter.java"
click node_rag_store "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/PgVectorVectorStoreConfig.java"
click node_rag_advisor "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/LoveAppRagCustomAdvisorFactory.java"
click node_agent_core "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/agent/YuManus.java"
click node_agent_loop "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/agent/ReActAgent.java"
click node_agent_state "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/agent/model/AgentState.java"
click node_tools_reg "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/tools/ToolRegistration.java"
click node_tools_suite "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/tools/WebSearchTool.java"
click node_demo_invoke "https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/demo/invoke/SpringAiAiInvoke.java"
click node_frontend_app "https://github.com/liyupi/yu-ai-agent/blob/master/yu-ai-agent-frontend/src/App.vue"
click node_frontend_chat "https://github.com/liyupi/yu-ai-agent/blob/master/yu-ai-agent-frontend/src/components/ChatRoom.vue"
click node_frontend_views "https://github.com/liyupi/yu-ai-agent/blob/master/yu-ai-agent-frontend/src/views/LoveMaster.vue"
click node_mcp_app "https://github.com/liyupi/yu-ai-agent/blob/master/yu-image-search-mcp-server/src/main/java/com/yupi/yuimagesearchmcpserver/YuImageSearchMcpServerApplication.java"
click node_mcp_tool "https://github.com/liyupi/yu-ai-agent/blob/master/yu-image-search-mcp-server/src/main/java/com/yupi/yuimagesearchmcpserver/tools/ImageSearchTool.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_app,node_backend_api,node_backend_health,node_backend_config,node_loveapp,node_chat_memory,node_rag_loader,node_rag_transform,node_rag_store,node_rag_advisor,node_agent_core,node_agent_loop,node_agent_state,node_tools_reg,node_tools_suite,node_demo_invoke toneBlue
class node_frontend_app,node_frontend_chat,node_frontend_views toneAmber
class node_mcp_app,node_mcp_tool toneMint
```

## Components

### Backend service

Spring Boot AI orchestration runtime

- [Spring Boot](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/YuAiAgentApplication.java): runtime · Main Java 21 backend entrypoint · `src/main/java/com/yupi/yuaiagent/YuAiAgentApplication.java`
- [HTTP API](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/controller/AiController.java): controller · Chat and health endpoints · `src/main/java/com/yupi/yuaiagent/controller/AiController.java`
- [Health API](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/controller/HealthController.java): controller · Service health endpoint · `src/main/java/com/yupi/yuaiagent/controller/HealthController.java`
- [Web config](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/config/CorsConfig.java): config · Cross-cutting Spring configuration · `src/main/java/com/yupi/yuaiagent/config/CorsConfig.java`
- [LoveApp](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/app/LoveApp.java): assistant domain · Romance conversation assistant orchestration · `src/main/java/com/yupi/yuaiagent/app/LoveApp.java`
- [File memory](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/chatmemory/FileBasedChatMemory.java): state store · Persistent conversation memory on disk · `src/main/java/com/yupi/yuaiagent/chatmemory/FileBasedChatMemory.java`
- [Doc loader](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/LoveAppDocumentLoader.java): rag ETL · Loads knowledge documents for retrieval · `src/main/java/com/yupi/yuaiagent/rag/LoveAppDocumentLoader.java`
- [Query prep](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/MyTokenTextSplitter.java): rag transform · Splitting, enrichment, and query rewriting · `src/main/java/com/yupi/yuaiagent/rag/MyTokenTextSplitter.java`
- [Vector store](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/PgVectorVectorStoreConfig.java): rag storage · PgVector and cloud vector-store integration · `src/main/java/com/yupi/yuaiagent/rag/PgVectorVectorStoreConfig.java`
- [RAG advisor](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/rag/LoveAppRagCustomAdvisorFactory.java): advisor pipeline · Spring AI retrieval wiring for LoveApp · `src/main/java/com/yupi/yuaiagent/rag/LoveAppRagCustomAdvisorFactory.java`
- [YuManus](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/agent/YuManus.java): agent runtime · Autonomous task agent orchestration · `src/main/java/com/yupi/yuaiagent/agent/YuManus.java`
- [Agent loop](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/agent/ReActAgent.java): reasoning loop · ReAct and tool-call execution layers · `src/main/java/com/yupi/yuaiagent/agent/ReActAgent.java`
- [Agent state](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/agent/model/AgentState.java): state model · Iterative reasoning and execution state · `src/main/java/com/yupi/yuaiagent/agent/model/AgentState.java`
- [Tool registry](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/tools/ToolRegistration.java): tool boundary · Registers callable capabilities for agents · `src/main/java/com/yupi/yuaiagent/tools/ToolRegistration.java`
- [Tool suite](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/tools/WebSearchTool.java): tools · File, web, terminal, download, PDF, and control tools · `src/main/java/com/yupi/yuaiagent/tools/WebSearchTool.java`
- [Model demos](https://github.com/liyupi/yu-ai-agent/blob/master/src/main/java/com/yupi/yuaiagent/demo/invoke/SpringAiAiInvoke.java): reference layer · Provider and API invocation examples · `src/main/java/com/yupi/yuaiagent/demo/invoke/SpringAiAiInvoke.java`

### Frontend app

Vue chat UI shell

- [Vue app](https://github.com/liyupi/yu-ai-agent/blob/master/yu-ai-agent-frontend/src/App.vue): runtime · Separate Vue 3 + Vite frontend · `yu-ai-agent-frontend/src/App.vue`
- [Chat UI](https://github.com/liyupi/yu-ai-agent/blob/master/yu-ai-agent-frontend/src/components/ChatRoom.vue): view · Shared conversational interface · `yu-ai-agent-frontend/src/components/ChatRoom.vue`
- [Product views](https://github.com/liyupi/yu-ai-agent/blob/master/yu-ai-agent-frontend/src/views/LoveMaster.vue): view set · Home, LoveMaster, and SuperAgent screens · `yu-ai-agent-frontend/src/views/LoveMaster.vue`

### MCP service

Separate image-search tool server

- [MCP server](https://github.com/liyupi/yu-ai-agent/blob/master/yu-image-search-mcp-server/src/main/java/com/yupi/yuimagesearchmcpserver/YuImageSearchMcpServerApplication.java): runtime · Standalone image-search MCP service · `yu-image-search-mcp-server/src/main/java/com/yupi/yuimagesearchmcpserver/YuImageSearchMcpServerApplication.java`
- [Image search](https://github.com/liyupi/yu-ai-agent/blob/master/yu-image-search-mcp-server/src/main/java/com/yupi/yuimagesearchmcpserver/tools/ImageSearchTool.java): mcp tool · Exposed image-search capability · `yu-image-search-mcp-server/src/main/java/com/yupi/yuimagesearchmcpserver/tools/ImageSearchTool.java`

## Connections

- Spring Boot → HTTP API: hosts · Backend exposes AI endpoints through controllers
- Spring Boot → Health API: hosts · Backend exposes health checks
- Spring Boot → Web config: uses · Applies web and CORS configuration
- HTTP API → LoveApp: routes chat · Chat requests enter the LoveApp domain
- HTTP API → YuManus: routes agent · Task requests enter the YuManus agent domain
- LoveApp → File memory: persists state · Conversation memory is stored on disk
- LoveApp → Doc loader: indexes docs · Loads markdown knowledge base
- Doc loader → Query prep: prepares · Documents are split and enriched before retrieval
- Query prep → Vector store: writes vectors · Prepared content is stored in the vector layer
- LoveApp → RAG advisor: retrieves via · RAG is wired through Spring AI advisors
- RAG advisor → Vector store: queries · Retrieval reads from the vector store
- YuManus → Agent loop: drives · YuManus delegates reasoning and execution to the agent loop
- Agent loop → Agent state: updates · Iterative reasoning state is maintained across steps
- Agent loop → Tool registry: invokes · Agent loop requests capabilities through registry
- Tool registry → Tool suite: exposes · Tools are made available to models and agents
- Agent loop → MCP server: calls external MCP · Agent can reach the separate MCP tool service
- HTTP API → Vue app: served to · Frontend sends requests to backend HTTP endpoints
- Vue app → Chat UI: contains · Shared chat shell component
- Vue app → Product views: contains · Product-specific views for the two assistant modes
- MCP server → Image search: hosts · Standalone service exposes image search tool
- Model demos → Spring Boot: references · Provider access patterns are shown as examples