# bunnycoder1999/springairagapp architecture

> Architecture diagram of the GitHub repository bunnycoder1999/springairagapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bunnycoder1999/springairagapp
- Repository: https://github.com/bunnycoder1999/springairagapp

## Overview

#### Purpose and Runtime
Spring Boot 3/Java 21 service implementing document ingestion, semantic retrieval, and grounded RAG chat. The application bootstrap is `src/main/java/com/example/SpringAiRagApp/SpringAiRagAppApplication.java`; runtime configuration is centralized in `src/main/resources/application.yml`.

It exposes an HTTP API on port 8080 for document upload and question answering, backed by PostgreSQL/pgvector and local Ollama models.

#### HTTP Entry Points
`src/main/java/com/example/SpringAiRagApp/controllers/DocumentController.java` accepts document uploads and initiates ingestion.  
`src/main/java/com/example/SpringAiRagApp/controllers/ChatController.java` accepts chat questions and returns answer/citation payloads.  
`src/main/java/com/example/SpringAiRagApp/controllers/AdminController.java` is the operational/admin boundary for managing the document corpus.

#### Document Persistence Model
Documents and their searchable units are separate persisted entities:
- `src/main/java/com/example/SpringAiRagApp/model/Document.java`
- `src/main/java/com/example/SpringAiRagApp/model/DocumentChunk.java`
- `src/main/java/com/example/SpringAiRagApp/enums/DocumentStatus.java`

The parent document tracks lifecycle/status; chunks carry extracted content, metadata, and vector-searchable representation. Repository boundaries are `src/main/java/com/example/SpringAiRagApp/repositories/DocumentRepository.java` and `src/main/java/com/example/SpringAiRagApp/repositories/DocumentChunkRepository.java`.

#### Ingestion Pipeline
`src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentIngestionService.java` orchestrates upload-to-index processing. Its stages are:
1. Parse PDF/Word content through `DocumentParser.java` (Apache Tika boundary).
2. Split extracted text via `DocumentChunker.java`.
3. Attach source metadata, including citation-relevant information, through `MetaDataEnricher.java`.
4. Persist the document/chunks and generate/store embeddings through configured Spring AI/pgvector integration.

This separates raw file interpretation from chunk construction and storage/indexing.

#### Retrieval and RAG Answering
`src/main/java/com/example/SpringAiRagApp/service/search/SemanticSearchService.java` converts a question into a vector-search request and retrieves relevant document chunks from pgvector. It is the retrieval boundary between application logic and the vector database.

`src/main/java/com/example/SpringAiRagApp/service/rag/RagChatService.java` composes retrieved context with the user question, invokes the chat model, and builds grounded responses. The system prompt is maintained at `src/main/resources/prompts/rag-system-prompt.st`; response contracts include `src/main/java/com/example/SpringAiRagApp/dto/ChatResponse.java` and `src/main/java/com/example/SpringAiRagApp/dto/Citation.java`.

#### Infrastructure and External Services
`docker-compose.yml` provisions PostgreSQL with pgvector and Ollama; database initialization is in `docker/init-db.sql`. `src/main/java/com/example/SpringAiRagApp/config/PgvectorConfig.java` configures vector-store access, while `ChatConfig.java` configures Spring AI chat behavior.

Primary flow: upload → parse → chunk/enrich → embed/index in PostgreSQL/pgvector; question → embed/retrieve chunks → prompt Ollama with context → return answer plus source citations.

Main entry points: [`src/main/java/com/example/SpringAiRagApp/service/rag/RagChatService.java`](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/rag/RagChatService.java) (Grounded RAG chat), [`src/main/java/com/example/SpringAiRagApp/repositories/DocumentChunkRepository.java`](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/repositories/DocumentChunkRepository.java) (Document repositories), [`src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentIngestionService.java`](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentIngestionService.java) (Document ingestion), [`docker-compose.yml`](https://github.com/bunnycoder1999/springairagapp/blob/main/docker-compose.yml) (PostgreSQL / pgvector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_document_api["Document upload API<br/>controller"]
  node_chat_api["Chat API<br/>controller"]
  node_admin_api["Corpus admin API<br/>controller"]
end

subgraph group_ingestion["Ingestion"]
  node_ingestion_service["Document ingestion<br/>orchestrator"]
  node_parser["Document parser<br/>Tika adapter"]
  node_chunker["Text chunker<br/>pipeline stage"]
  node_metadata_enricher["Metadata enricher<br/>pipeline stage"]
end

subgraph group_rag["Retrieval &amp; RAG"]
  node_semantic_search["Semantic search<br/>retrieval service"]
  node_rag_chat["Grounded RAG chat<br/>chat service"]
  node_rag_prompt["RAG system prompt<br/>prompt template"]
  node_chat_response["Answer &amp; citations<br/>response DTOs<br/>[ChatResponse.java]"]
end

subgraph group_storage["Persistence"]
  node_documents[("Documents<br/>JPA entity<br/>[Document.java]")]
  node_chunks[("Document chunks<br/>JPA entity<br/>[DocumentChunk.java]")]
  node_repositories["Document repositories<br/>repository boundary"]
end

subgraph group_infra["Infrastructure"]
  node_pgvector_config["Vector store config<br/>Spring AI config"]
  node_chat_config["Chat model config<br/>Spring AI config"]
  node_postgres[("PostgreSQL / pgvector<br/>vector database<br/>[docker-compose.yml]")]
  node_ollama{{"Ollama<br/>local AI models<br/>[docker-compose.yml]"}}
end

node_app{{"Spring Boot app<br/>bootstrap"}}
node_runtime_config["Runtime configuration<br/>Spring config<br/>[application.yml]"]

node_app -->|"loads"| node_runtime_config
node_document_api -->|"uploads"| node_ingestion_service
node_admin_api -->|"manages corpus"| node_repositories
node_ingestion_service -->|"parses file"| node_parser
node_parser -->|"extracted text"| node_chunker
node_chunker -->|"chunks"| node_metadata_enricher
node_metadata_enricher -->|"persists"| node_repositories
node_repositories -->|"stores"| node_documents
node_repositories -->|"stores"| node_chunks
node_chunks -->|"content and vectors"| node_postgres
node_ingestion_service -->|"indexes embeddings"| node_pgvector_config
node_pgvector_config -->|"vector-store access"| node_postgres
node_chat_api -->|"question"| node_rag_chat
node_rag_chat -->|"retrieves context"| node_semantic_search
node_semantic_search -->|"vector search"| node_postgres
node_rag_chat -->|"uses"| node_rag_prompt
node_rag_chat -->|"invokes model"| node_chat_config
node_chat_config -->|"chat requests"| node_ollama
node_rag_chat -->|"returns"| node_chat_response

click node_app "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/SpringAiRagAppApplication.java"
click node_runtime_config "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/resources/application.yml"
click node_document_api "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/controllers/DocumentController.java"
click node_chat_api "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/controllers/ChatController.java"
click node_admin_api "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/controllers/AdminController.java"
click node_ingestion_service "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentIngestionService.java"
click node_parser "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentParser.java"
click node_chunker "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentChunker.java"
click node_metadata_enricher "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/MetaDataEnricher.java"
click node_semantic_search "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/search/SemanticSearchService.java"
click node_rag_chat "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/rag/RagChatService.java"
click node_rag_prompt "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/resources/prompts/rag-system-prompt.st"
click node_chat_response "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/dto/ChatResponse.java"
click node_documents "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/model/Document.java"
click node_chunks "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/model/DocumentChunk.java"
click node_repositories "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/repositories/DocumentChunkRepository.java"
click node_pgvector_config "https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/config/PgvectorConfig.java"
click node_postgres "https://github.com/bunnycoder1999/springairagapp/blob/main/docker-compose.yml"
click node_ollama "https://github.com/bunnycoder1999/springairagapp/blob/main/docker-compose.yml"

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_document_api,node_chat_api,node_admin_api toneBlue
class node_ingestion_service,node_parser,node_chunker,node_metadata_enricher toneAmber
class node_semantic_search,node_rag_chat,node_rag_prompt,node_chat_response toneMint
class node_documents,node_chunks,node_repositories toneRose
class node_pgvector_config,node_chat_config,node_postgres,node_ollama toneIndigo
class node_app,node_runtime_config toneNeutral
```

## Components

### HTTP API

- [Document upload API](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/controllers/DocumentController.java): controller · `src/main/java/com/example/SpringAiRagApp/controllers/DocumentController.java`
- [Chat API](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/controllers/ChatController.java): controller · `src/main/java/com/example/SpringAiRagApp/controllers/ChatController.java`
- [Corpus admin API](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/controllers/AdminController.java): controller · `src/main/java/com/example/SpringAiRagApp/controllers/AdminController.java`

### Ingestion

- [Document ingestion](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentIngestionService.java): orchestrator · Runs upload-to-index processing. · `src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentIngestionService.java`
- [Document parser](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentParser.java): Tika adapter · `src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentParser.java`
- [Text chunker](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentChunker.java): pipeline stage · `src/main/java/com/example/SpringAiRagApp/service/ingestion/DocumentChunker.java`
- [Metadata enricher](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/ingestion/MetaDataEnricher.java): pipeline stage · Adds citation-relevant source metadata. · `src/main/java/com/example/SpringAiRagApp/service/ingestion/MetaDataEnricher.java`

### Retrieval & RAG

- [Semantic search](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/search/SemanticSearchService.java): retrieval service · Embeds questions and retrieves relevant chunks. · `src/main/java/com/example/SpringAiRagApp/service/search/SemanticSearchService.java`
- [Grounded RAG chat](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/service/rag/RagChatService.java): chat service · Builds context-grounded answers and citations. · `src/main/java/com/example/SpringAiRagApp/service/rag/RagChatService.java`
- [RAG system prompt](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/resources/prompts/rag-system-prompt.st): prompt template · `src/main/resources/prompts/rag-system-prompt.st`
- [Answer & citations](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/dto/ChatResponse.java): response DTOs · `src/main/java/com/example/SpringAiRagApp/dto/ChatResponse.java`

### Persistence

- [Documents](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/model/Document.java): JPA entity · Tracks parent document lifecycle and status. · `src/main/java/com/example/SpringAiRagApp/model/Document.java`
- [Document chunks](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/model/DocumentChunk.java): JPA entity · Stores searchable content, metadata, and vectors. · `src/main/java/com/example/SpringAiRagApp/model/DocumentChunk.java`
- [Document repositories](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/repositories/DocumentChunkRepository.java): repository boundary · `src/main/java/com/example/SpringAiRagApp/repositories/DocumentChunkRepository.java`

### Infrastructure

- [Vector store config](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/config/PgvectorConfig.java): Spring AI config · `src/main/java/com/example/SpringAiRagApp/config/PgvectorConfig.java`
- **Chat model config**: Spring AI config
- [PostgreSQL / pgvector](https://github.com/bunnycoder1999/springairagapp/blob/main/docker-compose.yml): vector database · `docker-compose.yml`
- [Ollama](https://github.com/bunnycoder1999/springairagapp/blob/main/docker-compose.yml): local AI models · `docker-compose.yml`

### Other components

- [Spring Boot app](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/java/com/example/SpringAiRagApp/SpringAiRagAppApplication.java): bootstrap · `src/main/java/com/example/SpringAiRagApp/SpringAiRagAppApplication.java`
- [Runtime configuration](https://github.com/bunnycoder1999/springairagapp/blob/main/src/main/resources/application.yml): Spring config · `src/main/resources/application.yml`

## Connections

- Spring Boot app → Runtime configuration: loads
- Document upload API → Document ingestion: uploads
- Corpus admin API → Document repositories: manages corpus
- Document ingestion → Document parser: parses file
- Document parser → Text chunker: extracted text
- Text chunker → Metadata enricher: chunks
- Metadata enricher → Document repositories: persists
- Document repositories → Documents: stores
- Document repositories → Document chunks: stores
- Document chunks → PostgreSQL / pgvector: content and vectors
- Document ingestion → Vector store config: indexes embeddings
- Vector store config → PostgreSQL / pgvector: vector-store access
- Chat API → Grounded RAG chat: question
- Grounded RAG chat → Semantic search: retrieves context
- Semantic search → PostgreSQL / pgvector: vector search
- Grounded RAG chat → RAG system prompt: uses
- Grounded RAG chat → Chat model config: invokes model
- Chat model config → Ollama: chat requests
- Grounded RAG chat → Answer & citations: returns