# piomin/spring-ai-apps architecture

> Architecture diagram of the GitHub repository piomin/spring-ai-apps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piomin/spring-ai-apps
- Repository: https://github.com/piomin/spring-ai-apps

## Overview

##### Project type and purpose
- This is a Spring Boot multi-module application demonstrating the Model Context Protocol (MCP) pattern via Spring AI.
- It consists of two MCP “server” microservices (account-mcp-service, person-mcp-service) exposing AI-powered Tools, and one MCP “client” application (sample-client) that calls them.

##### File structure
- Top level: `pom.xml` (parent POM), CI config, README.
- `spring-ai-mcp/` subfolder with three Maven modules:
- `account-mcp-service/`
- `person-mcp-service/`
- `sample-client/`
- Each service module follows standard Maven layout (`src/main/java`, `src/main/resources`, `src/test`).
- Packages: `pl.piomin.services` with subpackages for `model`, `repository`, and `tools`.
- `import.sql` seeds an embedded H2 database.
- `application.yml` configures server ports and Spring AI credentials.
- `sample-client` contains REST controllers (`AccountController`, `PersonController`) that invoke the MCP servers via Spring AI’s client APIs.

##### README for additional insights
- Confirms use of Spring AI and MCP concept.
- Indicates you must export an OpenAI API key before running.

##### Essential details
- Where `@Tool` beans live (`AccountTools.java`, `PersonTools.java`) and how they invoke the AI.
- Ports and config files (`application.yml`) that bind services to endpoints.
- MCP protocol flow: sample client assembles request → service’s Tool method → Spring AI client sends to model → response flows back the same path.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Sample Client
    subgraph "Sample Client (port 8080)"
        direction TB
        SC_Main["SampleClient.java"]:::app
        SC_AC["AccountController"]:::app
        SC_PC["PersonController"]:::app
        SC_Conf["application.yml"]:::config
    end

    %% Account MCP Service
    subgraph "Account MCP Service (port 8081)"
        direction TB
        AMS_Main["AccountMCPService.java"]:::app
        AMS_Ctrl["AccountController"]:::app
        AMS_Tools["AccountTools"]:::app
        AMS_Repo["AccountRepository"]:::app
        AMS_Config["application.yml"]:::config
        AMS_Seed["import.sql"]:::config
        AMS_DB[(H2 Account DB)]:::db
    end

    %% Person MCP Service
    subgraph "Person MCP Service (port 8082)"
        direction TB
        PMS_Main["PersonMCPServer.java"]:::app
        PMS_Ctrl["PersonController"]:::app
        PMS_Tools["PersonTools"]:::app
        PMS_Repo["PersonRepository"]:::app
        PMS_Model["Person & Gender Models"]:::app
        PMS_Config["application.yml"]:::config
        PMS_Seed["import.sql"]:::config
        PMS_DB[(H2 Person DB)]:::db
    end

    %% External AI Provider
    AI["External AI Provider"]:::cloud

    %% Interactions
    SC_AC -->|"REST POST /accounts"| AMS_Ctrl
    SC_PC -->|"REST POST /persons"| PMS_Ctrl

    AMS_Ctrl -->|"invoke Tool"| AMS_Tools
    PMS_Ctrl -->|"invoke Tool"| PMS_Tools

    AMS_Tools -.->|"Spring AI call"| AI
    PMS_Tools -.->|"Spring AI call"| AI

    AMS_Tools -->|"JPA save/find"| AMS_Repo
    PMS_Tools -->|"JPA save/find"| PMS_Repo

    AMS_Repo -->|"read/write"| AMS_DB
    PMS_Repo -->|"read/write"| PMS_DB

    %% Click Events - Sample Client
    click SC_Main "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/sample-client/src/main/java/pl/piomin/services/SampleClient.java"
    click SC_AC "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/sample-client/src/main/java/pl/piomin/services/controller/AccountController.java"
    click SC_PC "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/sample-client/src/main/java/pl/piomin/services/controller/PersonController.java"
    click SC_Conf "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/sample-client/src/main/resources/application.yml"

    %% Click Events - Account MCP Service
    click AMS_Main "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/account-mcp-service/src/main/java/pl/piomin/services/AccountMCPService.java"
    click AMS_Tools "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/account-mcp-service/src/main/java/pl/piomin/services/tools/AccountTools.java"
    click AMS_Repo "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/account-mcp-service/src/main/java/pl/piomin/services/repository/AccountRepository.java"
    click AMS_Config "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/account-mcp-service/src/main/resources/application.yml"
    click AMS_Seed "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/account-mcp-service/src/main/resources/import.sql"

    %% Click Events - Person MCP Service
    click PMS_Main "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/person-mcp-service/src/main/java/pl/piomin/services/PersonMCPServer.java"
    click PMS_Tools "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/person-mcp-service/src/main/java/pl/piomin/services/tools/PersonTools.java"
    click PMS_Repo "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/person-mcp-service/src/main/java/pl/piomin/services/repository/PersonRepository.java"
    click PMS_Config "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/person-mcp-service/src/main/resources/application.yml"
    click PMS_Seed "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/person-mcp-service/src/main/resources/import.sql"

    %% Click Events - Models
    click PMS_Model "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/person-mcp-service/src/main/java/pl/piomin/services/model/Person.java"
    click PMS_Model "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/person-mcp-service/src/main/java/pl/piomin/services/model/Gender.java"
    click PMS_Model "https://github.com/piomin/spring-ai-apps/blob/master/spring-ai-mcp/account-mcp-service/src/main/java/pl/piomin/services/model/Account.java"

    %% Styles
    classDef app fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px
    classDef cloud fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef config fill:#E6E6FA,stroke:#000,stroke-width:1px
```
