# yar83men/spring-boot-ai-mcp architecture

> Architecture diagram of the GitHub repository yar83men/spring-boot-ai-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yar83men/spring-boot-ai-mcp
- Repository: https://github.com/yar83men/spring-boot-ai-mcp

## Overview

This is a Spring AI application split into an HTTP-facing client and an MCP tool server. The main workflow is a user request through client controllers to AI services and back; other documented capabilities include RAG ingestion/retrieval, conversational memory, image understanding, web search, weather, exchange rates, file operations and Gmail subjects. The graph retains these feature branches, but several service implementations and routes were not sampled, so their internal call links are left out rather than inferred.

Main entry points: [`spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java`](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java) (Chat API), [`spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java`](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java) (Tool registration), [`spring_ai_mcp_client/src/main/java/com/openai/client/service/DocumentService.java`](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/DocumentService.java) (RAG services), [`spring_ai_mcp_client/src/main/java/com/openai/client/controller/DocumentController.java`](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/DocumentController.java) (Document upload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["AI client"]
  node_chat_api["Chat API"]
  node_chat_service["Chat services"]
  node_chat_config["Chat configuration"]
  node_memory[("Chat memory")]
  node_rag_api["Document upload"]
  node_rag["RAG services"]
  node_image["Image understanding"]
  node_image_api["Image API"]
  node_weather_api["Weather API"]
  node_weather_service["Weather service"]
  node_web_api["Web search API"]
  node_file_api["File operations"]
  node_file_service["File service"]
  node_exchange_api["Exchange API"]
  node_web_controller["Web search route"]
end

subgraph group_mcp["MCP tools"]
  node_mcp_config["Tool registration"]
  node_weather_tool["Weather tool"]
  node_exchange_tool["Exchange tool"]
  node_gmail_tool["Gmail subjects<br/>[GMailService.java]"]
end

subgraph group_integrations["External systems"]
  node_openai{{"OpenAI"}}
  node_pgvector[("PGVector")]
  node_weather_provider{{"Weather provider"}}
  node_central_bank{{"Central bank"}}
  node_gmail{{"Gmail"}}
  node_filesystem{{"Filesystem MCP"}}
end

node_user(("User"))

node_user -->|"submits request"| node_chat_api
node_chat_api -->|"calls chat"| node_chat_service
node_chat_config -.->|"configures client"| node_openai
node_chat_api -->|"calls memory chat"| node_memory
node_user -->|"uploads document"| node_rag_api
node_rag_api -->|"parses and saves"| node_rag
node_rag -.->|"stores documents"| node_pgvector
node_chat_api -->|"retrieves context"| node_rag
node_user -->|"submits image"| node_image_api
node_image_api -->|"calls analysis"| node_image
node_user -->|"requests forecast"| node_weather_api
node_weather_api -->|"calls weather"| node_weather_service
node_weather_service -.->|"formats response"| node_openai
node_user -.->|"requests search"| node_web_controller
node_web_controller -.->|"calls search"| node_web_api
node_web_api -->|"runs prompt"| node_openai
node_mcp_config -->|"registers tool"| node_weather_tool
node_mcp_config -->|"registers tool"| node_exchange_tool
node_mcp_config -->|"registers tool"| node_gmail_tool
node_weather_tool -->|"fetches forecast"| node_weather_provider
node_exchange_tool -->|"fetches rates"| node_central_bank
node_gmail_tool -->|"reads subjects"| node_gmail
node_user -.->|"requests file task"| node_file_api
node_file_api -->|"calls file service"| node_file_service
node_file_service -.->|"uses MCP server"| node_filesystem
node_user -.->|"requests conversion"| node_exchange_api

click node_chat_api "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java"
click node_chat_service "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/ChatAIServiceImpl.java"
click node_chat_config "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/configuration/ChatClientCustomConfiguration.java"
click node_memory "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/ChatMemoryService.java"
click node_rag_api "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/DocumentController.java"
click node_rag "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/DocumentService.java"
click node_image "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/ImageAIServiceImpl.java"
click node_image_api "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/ImageController.java"
click node_weather_api "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/WeatherController.java"
click node_weather_service "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/WeatherServiceImpl.java"
click node_web_api "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/WebSearchAiServiceImpl.java"
click node_mcp_config "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java"
click node_weather_tool "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/service/WeatherApiToolService.java"
click node_exchange_tool "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/service/ExchangeCbrToolService.java"
click node_gmail_tool "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/service/GMailService.java"
click node_file_api "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/FileCreationAIController.java"
click node_file_service "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/FileCreatingAIService.java"
click node_exchange_api "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/ExchangeController.java"
click node_web_controller "https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/WebSearchAiController.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_chat_api,node_chat_service,node_chat_config,node_memory,node_rag_api,node_rag,node_image,node_image_api,node_weather_api,node_weather_service,node_web_api,node_file_api,node_file_service,node_exchange_api,node_web_controller,node_user toneBlue
class node_mcp_config,node_weather_tool,node_exchange_tool,node_gmail_tool toneAmber
class node_openai,node_pgvector,node_weather_provider,node_central_bank,node_gmail,node_filesystem toneMint
```

## Components

### AI client

- [Chat API](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java): `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java`
- [Chat services](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/ChatAIServiceImpl.java): `spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/ChatAIServiceImpl.java`
- [Chat configuration](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/configuration/ChatClientCustomConfiguration.java): `spring_ai_mcp_client/src/main/java/com/openai/client/configuration/ChatClientCustomConfiguration.java`
- [Chat memory](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/ChatMemoryService.java): `spring_ai_mcp_client/src/main/java/com/openai/client/service/ChatMemoryService.java`
- [Document upload](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/DocumentController.java): `spring_ai_mcp_client/src/main/java/com/openai/client/controller/DocumentController.java`
- [RAG services](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/DocumentService.java): `spring_ai_mcp_client/src/main/java/com/openai/client/service/DocumentService.java`
- [Image understanding](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/ImageAIServiceImpl.java): `spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/ImageAIServiceImpl.java`
- [Image API](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/ImageController.java): `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ImageController.java`
- [Weather API](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/WeatherController.java): `spring_ai_mcp_client/src/main/java/com/openai/client/controller/WeatherController.java`
- [Weather service](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/WeatherServiceImpl.java): `spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/WeatherServiceImpl.java`
- [Web search API](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/WebSearchAiServiceImpl.java): `spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/WebSearchAiServiceImpl.java`
- [File operations](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/FileCreationAIController.java): `spring_ai_mcp_client/src/main/java/com/openai/client/controller/FileCreationAIController.java`
- [File service](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/service/FileCreatingAIService.java): `spring_ai_mcp_client/src/main/java/com/openai/client/service/FileCreatingAIService.java`
- [Exchange API](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/ExchangeController.java): `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ExchangeController.java`
- [Web search route](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_client/src/main/java/com/openai/client/controller/WebSearchAiController.java): `spring_ai_mcp_client/src/main/java/com/openai/client/controller/WebSearchAiController.java`

### MCP tools

- [Tool registration](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java): `spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java`
- [Weather tool](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/service/WeatherApiToolService.java): `spring_ai_mcp_server/src/main/java/com/openai/server/service/WeatherApiToolService.java`
- [Exchange tool](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/service/ExchangeCbrToolService.java): `spring_ai_mcp_server/src/main/java/com/openai/server/service/ExchangeCbrToolService.java`
- [Gmail subjects](https://github.com/yar83men/spring-boot-ai-mcp/blob/main/spring_ai_mcp_server/src/main/java/com/openai/server/service/GMailService.java): `spring_ai_mcp_server/src/main/java/com/openai/server/service/GMailService.java`

### External systems

- **OpenAI**
- **PGVector**
- **Weather provider**
- **Central bank**
- **Gmail**
- **Filesystem MCP**

### Other components

- **User**

## Connections

- User → Chat API: submits request (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java`)
- Chat API → Chat services: calls chat (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java`)
- Chat configuration → OpenAI: configures client (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/configuration/ChatClientCustomConfiguration.java`)
- Chat API → Chat memory: calls memory chat (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java`)
- User → Document upload: uploads document (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/DocumentController.java`)
- Document upload → RAG services: parses and saves (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/DocumentController.java`)
- RAG services → PGVector: stores documents
- Chat API → RAG services: retrieves context (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ChatController.java`)
- User → Image API: submits image (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ImageController.java`)
- Image API → Image understanding: calls analysis (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/ImageController.java`)
- User → Weather API: requests forecast (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/WeatherController.java`)
- Weather API → Weather service: calls weather (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/WeatherController.java`)
- Weather service → OpenAI: formats response
- User → Web search route: requests search
- Web search route → Web search API: calls search
- Web search API → OpenAI: runs prompt (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/service/impl/WebSearchAiServiceImpl.java`)
- Tool registration → Weather tool: registers tool (evidence: `spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java`)
- Tool registration → Exchange tool: registers tool (evidence: `spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java`)
- Tool registration → Gmail subjects: registers tool (evidence: `spring_ai_mcp_server/src/main/java/com/openai/server/configuration/McpServerConfiguration.java`)
- Weather tool → Weather provider: fetches forecast (evidence: `spring_ai_mcp_server/src/main/java/com/openai/server/service/WeatherApiToolService.java`)
- Exchange tool → Central bank: fetches rates (evidence: `spring_ai_mcp_server/src/main/java/com/openai/server/service/ExchangeCbrToolService.java`)
- Gmail subjects → Gmail: reads subjects (evidence: `spring_ai_mcp_server/src/main/java/com/openai/server/service/GMailService.java`)
- User → File operations: requests file task
- File operations → File service: calls file service (evidence: `spring_ai_mcp_client/src/main/java/com/openai/client/controller/FileCreationAIController.java`)
- File service → Filesystem MCP: uses MCP server
- User → Exchange API: requests conversion
