# santaigh/calc-api-app architecture

> Architecture diagram of the GitHub repository santaigh/calc-api-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santaigh/calc-api-app
- Repository: https://github.com/santaigh/calc-api-app

## Overview

This is a calculator API with both direct arithmetic endpoints and an LLM-assisted chat workflow. Chat requests are parsed into an operation and operands, dispatched to a deterministic operation agent, calculated through an MCP tool server, then phrased as a response. The graph also preserves the direct calculator path and the four operation-specific agents. The source excerpts establish backend calls; static UI files are present, but their request wiring was not shown, so no UI-to-API edges are asserted.

Main entry points: [`src/main/java/com/calc/api/agent/CalcAgent.java`](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalcAgent.java) (Chat Orchestrator), [`src/main/java/com/calc/api/agent/CalcMcpClient.java`](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalcMcpClient.java) (MCP Client), [`src/main/java/com/calc/api/controller/CalculatorController.java`](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/controller/CalculatorController.java) (Calculator API), [`src/main/java/com/calc/api/controller/ChatController.java`](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/controller/ChatController.java) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Data"]
  node_calc_controller["Calculator API"]
  node_calc_request["Calculation Request"]
  node_calculator_service["Calculator Service"]
  node_chat_controller["Chat API"]
  node_chat_request["Chat Request<br/>[ChatRequest.java]"]
  node_chat_response["Chat Response<br/>[ChatResponse.java]"]
  node_parsed_calculation["Parsed Calculation"]
  node_chat_ui["Chat Web UI<br/>[chat.html]"]
  node_chat_script["Chat UI Script<br/>[chat.js]"]
  node_calculator_ui["Calculator Web UI<br/>[index.html]"]
  node_calculator_script["Calculator UI Script<br/>[app.js]"]
end

subgraph group_chat["Chat Workflow"]
  node_calc_agent["Chat Orchestrator<br/>[CalcAgent.java]"]
  node_add_agent["Addition Agent<br/>[AddAgent.java]"]
  node_subtract_agent["Subtraction Agent<br/>[SubtractAgent.java]"]
  node_multiply_agent["Multiplication Agent<br/>[MultiplyAgent.java]"]
  node_division_agent["Division Agent<br/>[DivisionAgent.java]"]
  node_operation_agent["Operation Contract"]
end

subgraph group_mcp["Calculator MCP"]
  node_mcp_client["MCP Client<br/>[CalcMcpClient.java]"]
  node_unavailable_exception["Unavailable Error"]
end

node_user(("Web User"))
node_llm["Language Model"]
node_mcp_server["Calculator MCP Server"]

node_user -->|"submits calculation"| node_calc_controller
node_user -->|"sends message"| node_chat_controller
node_calc_controller -->|"accepts"| node_calc_request
node_calc_controller -->|"calls"| node_calculator_service
node_chat_controller -->|"accepts"| node_chat_request
node_chat_controller -->|"delegates to"| node_calc_agent
node_calc_agent -->|"parses into"| node_parsed_calculation
node_calc_agent -->|"prompts twice"| node_llm
node_calc_agent -->|"dispatches to"| node_add_agent
node_calc_agent -->|"dispatches to"| node_subtract_agent
node_calc_agent -->|"dispatches to"| node_multiply_agent
node_calc_agent -->|"dispatches to"| node_division_agent
node_calc_agent -->|"returns"| node_chat_response
node_add_agent -->|"calls"| node_mcp_client
node_subtract_agent -->|"calls"| node_mcp_client
node_multiply_agent -->|"calls"| node_mcp_client
node_division_agent -->|"calls"| node_mcp_client
node_mcp_client -->|"calls tool"| node_mcp_server
node_mcp_client -->|"throws on failure"| node_unavailable_exception
node_chat_ui -.->|"loads"| node_chat_script
node_calculator_ui -.->|"loads"| node_calculator_script

click node_calc_controller "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/controller/CalculatorController.java"
click node_calc_request "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/CalculationRequest.java"
click node_calculator_service "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/service/CalculatorService.java"
click node_chat_controller "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/controller/ChatController.java"
click node_chat_request "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/ChatRequest.java"
click node_chat_response "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/ChatResponse.java"
click node_parsed_calculation "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/ParsedCalculation.java"
click node_calc_agent "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalcAgent.java"
click node_add_agent "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/AddAgent.java"
click node_subtract_agent "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/SubtractAgent.java"
click node_multiply_agent "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/MultiplyAgent.java"
click node_division_agent "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/DivisionAgent.java"
click node_operation_agent "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/OperationAgent.java"
click node_mcp_client "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalcMcpClient.java"
click node_unavailable_exception "https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalculatorUnavailableException.java"
click node_chat_ui "https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/chat.html"
click node_chat_script "https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/js/chat.js"
click node_calculator_ui "https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/index.html"
click node_calculator_script "https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/js/app.js"

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_calc_controller,node_calc_request,node_calculator_service,node_chat_controller,node_chat_request,node_chat_response,node_parsed_calculation,node_chat_ui,node_chat_script,node_calculator_ui,node_calculator_script,node_user toneBlue
class node_calc_agent,node_add_agent,node_subtract_agent,node_multiply_agent,node_division_agent,node_operation_agent toneAmber
class node_mcp_client,node_unavailable_exception,node_mcp_server toneMint
class node_llm toneIndigo
```

## Components

### API and Data

- [Calculator API](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/controller/CalculatorController.java): `src/main/java/com/calc/api/controller/CalculatorController.java`
- [Calculation Request](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/CalculationRequest.java): `src/main/java/com/calc/api/dto/CalculationRequest.java`
- [Calculator Service](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/service/CalculatorService.java): `src/main/java/com/calc/api/service/CalculatorService.java`
- [Chat API](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/controller/ChatController.java): `src/main/java/com/calc/api/controller/ChatController.java`
- [Chat Request](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/ChatRequest.java): `src/main/java/com/calc/api/dto/ChatRequest.java`
- [Chat Response](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/ChatResponse.java): `src/main/java/com/calc/api/dto/ChatResponse.java`
- [Parsed Calculation](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/dto/ParsedCalculation.java): `src/main/java/com/calc/api/dto/ParsedCalculation.java`
- [Chat Web UI](https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/chat.html): `src/main/resources/static/chat.html`
- [Chat UI Script](https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/js/chat.js): `src/main/resources/static/js/chat.js`
- [Calculator Web UI](https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/index.html): `src/main/resources/static/index.html`
- [Calculator UI Script](https://github.com/santaigh/calc-api-app/blob/main/src/main/resources/static/js/app.js): `src/main/resources/static/js/app.js`

### Chat Workflow

- [Chat Orchestrator](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalcAgent.java): `src/main/java/com/calc/api/agent/CalcAgent.java`
- [Addition Agent](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/AddAgent.java): `src/main/java/com/calc/api/agent/AddAgent.java`
- [Subtraction Agent](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/SubtractAgent.java): `src/main/java/com/calc/api/agent/SubtractAgent.java`
- [Multiplication Agent](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/MultiplyAgent.java): `src/main/java/com/calc/api/agent/MultiplyAgent.java`
- [Division Agent](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/DivisionAgent.java): `src/main/java/com/calc/api/agent/DivisionAgent.java`
- [Operation Contract](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/OperationAgent.java): `src/main/java/com/calc/api/agent/OperationAgent.java`

### Calculator MCP

- [MCP Client](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalcMcpClient.java): `src/main/java/com/calc/api/agent/CalcMcpClient.java`
- [Unavailable Error](https://github.com/santaigh/calc-api-app/blob/main/src/main/java/com/calc/api/agent/CalculatorUnavailableException.java): `src/main/java/com/calc/api/agent/CalculatorUnavailableException.java`

### Other components

- **Web User**
- **Language Model**
- **Calculator MCP Server**

## Connections

- Web User → Calculator API: submits calculation (evidence: `src/main/java/com/calc/api/controller/CalculatorController.java`)
- Web User → Chat API: sends message (evidence: `src/main/java/com/calc/api/controller/ChatController.java`)
- Calculator API → Calculation Request: accepts (evidence: `src/main/java/com/calc/api/controller/CalculatorController.java`)
- Calculator API → Calculator Service: calls (evidence: `src/main/java/com/calc/api/controller/CalculatorController.java`)
- Chat API → Chat Request: accepts (evidence: `src/main/java/com/calc/api/controller/ChatController.java`)
- Chat API → Chat Orchestrator: delegates to (evidence: `src/main/java/com/calc/api/controller/ChatController.java`)
- Chat Orchestrator → Parsed Calculation: parses into (evidence: `src/main/java/com/calc/api/agent/CalcAgent.java`)
- Chat Orchestrator → Language Model: prompts twice (evidence: `src/main/java/com/calc/api/agent/CalcAgent.java`)
- Chat Orchestrator → Addition Agent: dispatches to (evidence: `src/main/java/com/calc/api/agent/CalcAgent.java`)
- Chat Orchestrator → Subtraction Agent: dispatches to (evidence: `src/main/java/com/calc/api/agent/CalcAgent.java`)
- Chat Orchestrator → Multiplication Agent: dispatches to (evidence: `src/main/java/com/calc/api/agent/CalcAgent.java`)
- Chat Orchestrator → Division Agent: dispatches to (evidence: `src/main/java/com/calc/api/agent/CalcAgent.java`)
- Chat Orchestrator → Chat Response: returns (evidence: `src/main/java/com/calc/api/agent/CalcAgent.java`)
- Addition Agent → MCP Client: calls (evidence: `src/main/java/com/calc/api/agent/AddAgent.java`)
- Subtraction Agent → MCP Client: calls (evidence: `src/main/java/com/calc/api/agent/SubtractAgent.java`)
- Multiplication Agent → MCP Client: calls (evidence: `src/main/java/com/calc/api/agent/MultiplyAgent.java`)
- Division Agent → MCP Client: calls (evidence: `src/main/java/com/calc/api/agent/DivisionAgent.java`)
- MCP Client → Calculator MCP Server: calls tool (evidence: `src/main/java/com/calc/api/agent/CalcMcpClient.java`)
- MCP Client → Unavailable Error: throws on failure (evidence: `src/main/java/com/calc/api/agent/CalcMcpClient.java`)
- Chat Web UI → Chat UI Script: loads
- Calculator Web UI → Calculator UI Script: loads
