# rohan-girsa/ai-gateway-spring architecture

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

- Interactive diagram: https://gitdiagram.com/rohan-girsa/ai-gateway-spring
- Repository: https://github.com/rohan-girsa/ai-gateway-spring

## Overview

AI Gateway is a Spring Boot chat API that accepts requests, prepares provider-neutral LLM calls, and returns JSON replies or SSE streams. Its principal workflow includes session-memory selection, optional document processing, provider-specific request/response mapping, and response delivery; separate endpoints expose history, memory clearing, and configured providers. The README documents these relationships and the major capabilities, but no source excerpts were supplied, so implementation-level call ownership cannot be verified beyond those documented flows.

Main entry points: [`src/main/java/com/example/aigateway/service/ChatService.java`](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/service/ChatService.java) (Chat orchestration), [`src/main/java/com/example/aigateway/provider/LlmRequest.java`](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/LlmRequest.java) (LLM request), [`src/main/java/com/example/aigateway/provider/openai/OpenAiCompatibleProvider.java`](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/openai/OpenAiCompatibleProvider.java) (OpenAI-compatible adapter), [`src/main/java/com/example/aigateway/provider/anthropic/AnthropicProvider.java`](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/anthropic/AnthropicProvider.java) (Anthropic adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and chat orchestration"]
  node_controller["Chat endpoints"]
  node_errors["Error handling"]
  node_chatservice["Chat orchestration<br/>[ChatService.java]"]
  node_prepared["Prepared chat<br/>[PreparedChat.java]"]
  node_chatmodels["Chat models<br/>[ChatRequest.java]"]
  node_responsemodel["Chat response<br/>[ChatResponse.java]"]
end

subgraph group_context["Conversation context"]
  node_memory[("Session memory")]
  node_inmemory[("In-memory store")]
  node_documents["Document handling"]
  node_fetcher["Safe URL fetch"]
  node_extractor["Text extraction"]
  node_docsupport["Provider document support"]
end

subgraph group_providers["Provider integration"]
  node_providerregistry["Provider registry"]
  node_llmrequest["LLM request<br/>[LlmRequest.java]"]
  node_llmresult["LLM result<br/>[LlmResult.java]"]
  node_openai["OpenAI-compatible adapter"]
  node_openaimapper["OpenAI mapper<br/>[OpenAiMapper.java]"]
  node_anthropic["Anthropic adapter"]
  node_anthropicmapper["Anthropic mapper"]
  node_perplexity["Perplexity adapter"]
  node_perplexitymapper["Perplexity mapper"]
end

subgraph group_configuration["Runtime configuration"]
  node_config["AI settings<br/>[AiProperties.java]"]
end

node_client(("API client"))
node_vendor{{"LLM provider APIs"}}

node_client -->|"sends requests"| node_controller
node_controller -->|"delegates chat"| node_chatservice
node_chatservice -->|"prepares request"| node_prepared
node_chatservice -->|"uses session memory"| node_memory
node_inmemory -->|"implements"| node_memory
node_chatservice -->|"handles documents"| node_documents
node_documents -->|"fetches URLs"| node_fetcher
node_documents -->|"extracts text"| node_extractor
node_chatservice -.->|"selects provider"| node_providerregistry
node_chatservice -->|"creates request"| node_llmrequest
node_llmrequest -->|"maps request"| node_openaimapper
node_llmrequest -->|"maps request"| node_anthropicmapper
node_llmrequest -->|"maps request"| node_perplexitymapper
node_openaimapper -->|"builds provider DTO"| node_openai
node_anthropicmapper -->|"builds provider DTO"| node_anthropic
node_perplexitymapper -->|"builds provider DTO"| node_perplexity
node_openai -->|"calls API"| node_vendor
node_anthropic -->|"calls API"| node_vendor
node_perplexity -->|"calls API"| node_vendor
node_openai -->|"maps response"| node_llmresult
node_anthropic -->|"maps response"| node_llmresult
node_perplexity -->|"maps response"| node_llmresult
node_llmresult -->|"returns result"| node_chatservice
node_chatservice -->|"returns reply or stream"| node_controller
node_docsupport -->|"supports file parts"| node_openai
node_docsupport -->|"supports document blocks"| node_anthropic
node_docsupport -->|"supports input files"| node_perplexity
node_config -.->|"configures providers"| node_providerregistry

click node_controller "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/web/ChatController.java"
click node_errors "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/web/GlobalExceptionHandler.java"
click node_chatservice "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/service/ChatService.java"
click node_prepared "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/service/PreparedChat.java"
click node_chatmodels "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/model/ChatRequest.java"
click node_responsemodel "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/model/ChatResponse.java"
click node_memory "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/memory/ConversationMemory.java"
click node_inmemory "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/memory/InMemoryConversationMemory.java"
click node_documents "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentService.java"
click node_fetcher "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentFetcher.java"
click node_extractor "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentTextExtractor.java"
click node_docsupport "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentSupport.java"
click node_providerregistry "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/ProviderRegistry.java"
click node_llmrequest "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/LlmRequest.java"
click node_llmresult "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/LlmResult.java"
click node_openai "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/openai/OpenAiCompatibleProvider.java"
click node_openaimapper "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/openai/OpenAiMapper.java"
click node_anthropic "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/anthropic/AnthropicProvider.java"
click node_anthropicmapper "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/anthropic/AnthropicMapper.java"
click node_perplexity "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/perplexity/PerplexityAgentProvider.java"
click node_perplexitymapper "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/perplexity/PerplexityMapper.java"
click node_config "https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/config/AiProperties.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_controller,node_errors,node_chatservice,node_prepared,node_chatmodels,node_responsemodel,node_client toneBlue
class node_memory,node_inmemory,node_documents,node_fetcher,node_extractor,node_docsupport toneAmber
class node_providerregistry,node_llmrequest,node_llmresult,node_openai,node_openaimapper,node_anthropic,node_anthropicmapper,node_perplexity,node_perplexitymapper,node_vendor toneMint
class node_config toneRose
```

## Components

### API and chat orchestration

- [Chat endpoints](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/web/ChatController.java): `src/main/java/com/example/aigateway/web/ChatController.java`
- [Error handling](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/web/GlobalExceptionHandler.java): `src/main/java/com/example/aigateway/web/GlobalExceptionHandler.java`
- [Chat orchestration](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/service/ChatService.java): `src/main/java/com/example/aigateway/service/ChatService.java`
- [Prepared chat](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/service/PreparedChat.java): `src/main/java/com/example/aigateway/service/PreparedChat.java`
- [Chat models](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/model/ChatRequest.java): `src/main/java/com/example/aigateway/model/ChatRequest.java`
- [Chat response](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/model/ChatResponse.java): `src/main/java/com/example/aigateway/model/ChatResponse.java`

### Conversation context

- [Session memory](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/memory/ConversationMemory.java): `src/main/java/com/example/aigateway/memory/ConversationMemory.java`
- [In-memory store](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/memory/InMemoryConversationMemory.java): `src/main/java/com/example/aigateway/memory/InMemoryConversationMemory.java`
- [Document handling](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentService.java): `src/main/java/com/example/aigateway/document/DocumentService.java`
- [Safe URL fetch](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentFetcher.java): `src/main/java/com/example/aigateway/document/DocumentFetcher.java`
- [Text extraction](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentTextExtractor.java): `src/main/java/com/example/aigateway/document/DocumentTextExtractor.java`
- [Provider document support](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/document/DocumentSupport.java): `src/main/java/com/example/aigateway/document/DocumentSupport.java`

### Provider integration

- [Provider registry](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/ProviderRegistry.java): `src/main/java/com/example/aigateway/provider/ProviderRegistry.java`
- [LLM request](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/LlmRequest.java): `src/main/java/com/example/aigateway/provider/LlmRequest.java`
- [LLM result](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/LlmResult.java): `src/main/java/com/example/aigateway/provider/LlmResult.java`
- [OpenAI-compatible adapter](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/openai/OpenAiCompatibleProvider.java): `src/main/java/com/example/aigateway/provider/openai/OpenAiCompatibleProvider.java`
- [OpenAI mapper](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/openai/OpenAiMapper.java): `src/main/java/com/example/aigateway/provider/openai/OpenAiMapper.java`
- [Anthropic adapter](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/anthropic/AnthropicProvider.java): `src/main/java/com/example/aigateway/provider/anthropic/AnthropicProvider.java`
- [Anthropic mapper](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/anthropic/AnthropicMapper.java): `src/main/java/com/example/aigateway/provider/anthropic/AnthropicMapper.java`
- [Perplexity adapter](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/perplexity/PerplexityAgentProvider.java): `src/main/java/com/example/aigateway/provider/perplexity/PerplexityAgentProvider.java`
- [Perplexity mapper](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/provider/perplexity/PerplexityMapper.java): `src/main/java/com/example/aigateway/provider/perplexity/PerplexityMapper.java`

### Runtime configuration

- [AI settings](https://github.com/rohan-girsa/ai-gateway-spring/blob/master/src/main/java/com/example/aigateway/config/AiProperties.java): `src/main/java/com/example/aigateway/config/AiProperties.java`

### Other components

- **API client**
- **LLM provider APIs**

## Connections

- API client → Chat endpoints: sends requests (evidence: `README.md`)
- Chat endpoints → Chat orchestration: delegates chat (evidence: `README.md`)
- Chat orchestration → Prepared chat: prepares request (evidence: `README.md`)
- Chat orchestration → Session memory: uses session memory (evidence: `README.md`)
- In-memory store → Session memory: implements (evidence: `README.md`)
- Chat orchestration → Document handling: handles documents (evidence: `README.md`)
- Document handling → Safe URL fetch: fetches URLs (evidence: `README.md`)
- Document handling → Text extraction: extracts text (evidence: `README.md`)
- Chat orchestration → Provider registry: selects provider
- Chat orchestration → LLM request: creates request (evidence: `README.md`)
- LLM request → OpenAI mapper: maps request (evidence: `README.md`)
- LLM request → Anthropic mapper: maps request (evidence: `README.md`)
- LLM request → Perplexity mapper: maps request (evidence: `README.md`)
- OpenAI mapper → OpenAI-compatible adapter: builds provider DTO (evidence: `README.md`)
- Anthropic mapper → Anthropic adapter: builds provider DTO (evidence: `README.md`)
- Perplexity mapper → Perplexity adapter: builds provider DTO (evidence: `README.md`)
- OpenAI-compatible adapter → LLM provider APIs: calls API (evidence: `README.md`)
- Anthropic adapter → LLM provider APIs: calls API (evidence: `README.md`)
- Perplexity adapter → LLM provider APIs: calls API (evidence: `README.md`)
- OpenAI-compatible adapter → LLM result: maps response (evidence: `README.md`)
- Anthropic adapter → LLM result: maps response (evidence: `README.md`)
- Perplexity adapter → LLM result: maps response (evidence: `README.md`)
- LLM result → Chat orchestration: returns result (evidence: `README.md`)
- Chat orchestration → Chat endpoints: returns reply or stream (evidence: `README.md`)
- Provider document support → OpenAI-compatible adapter: supports file parts (evidence: `README.md`)
- Provider document support → Anthropic adapter: supports document blocks (evidence: `README.md`)
- Provider document support → Perplexity adapter: supports input files (evidence: `README.md`)
- AI settings → Provider registry: configures providers