# amitksoftech/rag-mvp1 architecture

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

- Interactive diagram: https://gitdiagram.com/amitksoftech/rag-mvp1
- Repository: https://github.com/amitksoftech/rag-mvp1

## Overview

#### Purpose and Runtime
This is a Java/Spring Boot RAG MVP for uploading knowledge documents, storing their metadata and files, asynchronously ingesting content into a vector store, and presenting document/admin views. The application starts at `src/main/java/com/ai/applications/rag/ragmvp1/Ragmvp1Application.java`; Maven build/runtime dependencies are defined in `pom.xml`.

#### HTTP and Server-rendered UI
Spring MVC controllers expose the primary interaction surfaces: home/login, document upload/list/detail, and administrative operations. Server-rendered Thymeleaf-style templates form the UI rather than a separate frontend.
- `src/main/java/com/ai/applications/rag/ragmvp1/controller/DocumentController.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/controller/AdminController.java`
- `src/main/resources/templates/documents/upload.html`

#### Document Lifecycle and Persistent Metadata
`DocumentService` coordinates document-facing lifecycle operations, while `DocumentStorageService` manages physical uploaded files. `StoredDocument`, status models, and `KnowledgeDocument` represent lifecycle/state and persisted knowledge-document metadata. Files are presently rooted under the repository’s `data/uploads` directory.
- `src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentService.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentStorageService.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/models/entity/KnowledgeDocument.java`

#### Event-driven Asynchronous Ingestion
Upload completion is decoupled from processing through `DocumentUploadedEvent`. `IngestionEventListener` receives the event and delegates to `IngestionProcessor`; async execution is configured separately. This boundary lets upload requests persist/return independently of extraction, chunking, embedding, and index status transitions.
- `src/main/java/com/ai/applications/rag/ragmvp1/models/DocumentUploadedEvent.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionEventListener.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/config/AsyncConfiguration.java`

#### RAG Indexing Boundary
`IngestionProcessor` is the ingestion orchestration stage and `EmbeddingIndexer` is the explicit embedding/vector-index adapter boundary. Embedding and vector-store beans/properties are isolated in configuration, allowing provider or backing-store changes without restructuring controllers or document persistence.
- `src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionProcessor.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/service/EmbeddingIndexer.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/config/EmbeddingConfiguration.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/config/VectorStoreConfiguration.java`

#### Database, Security, and Administration
Spring Data repositories persist users and knowledge documents. Security authenticates against database users through a custom user-details service and configuration. Administrative document operations and ingestion statistics are surfaced through dedicated services/controller and template.
- `src/main/java/com/ai/applications/rag/ragmvp1/repository/KnowledgeDocumentRepository.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/security/SecurityConfiguration.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/service/StatisticsService.java`

#### Configuration and Infrastructure
Application properties define the operational wiring; typed storage/bootstrap properties support configurable startup and file-storage behavior. Material infrastructure consists of Spring Boot’s web, async, security, persistence, local file storage, embedding provider, and vector-store integration; exact providers are not inferable from the supplied tree.
- `src/main/resources/application.yml`
- `src/main/java/com/ai/applications/rag/ragmvp1/config/StorageConfiguration.java`
- `src/main/java/com/ai/applications/rag/ragmvp1/config/BootstrapProperties.java`

Main entry points: [`src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentService.java`](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentService.java) (Document service), [`src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionProcessor.java`](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionProcessor.java) (Ingestion processor), [`src/main/java/com/ai/applications/rag/ragmvp1/repository/KnowledgeDocumentRepository.java`](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/repository/KnowledgeDocumentRepository.java) (Document repository), [`src/main/java/com/ai/applications/rag/ragmvp1/Ragmvp1Application.java`](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/Ragmvp1Application.java) (Spring Boot app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web & Admin"]
  node_controllers["Document controllers<br/>Spring MVC"]
  node_admin["Admin controller<br/>Spring MVC"]
  node_upload_ui["Upload page<br/>server template<br/>[upload.html]"]
end

subgraph group_documents["Document Lifecycle"]
  node_document_service["Document service<br/>lifecycle service"]
  node_storage["File storage service"]
  node_files[("Uploaded files<br/>local file storage")]
  node_knowledge_document["Knowledge document<br/>persistent entity"]
  node_statistics["Statistics service<br/>admin service"]
end

subgraph group_ingestion["Async Ingestion"]
  node_upload_event["Document uploaded event<br/>application event"]
  node_listener["Ingestion event listener<br/>async event listener"]
  node_processor["Ingestion processor<br/>ingestion orchestrator"]
  node_indexer["Embedding indexer<br/>vector adapter"]
  node_vector_store[("Vector store<br/>RAG index")]
end

subgraph group_platform["Platform &amp; Persistence"]
  node_app{{"Spring Boot app<br/>application bootstrap"}}
  node_security["Security configuration<br/>Spring Security"]
  node_document_repo[("Document repository<br/>Spring Data repository")]
  node_async_config["Async configuration<br/>executor configuration"]
  node_rag_config["Embedding/vector configuration<br/>integration configuration"]
  node_app_config["Application configuration<br/>properties<br/>[application.yml]"]
end

node_app -->|"starts MVC"| node_controllers
node_app -->|"applies security"| node_security
node_app -->|"loads"| node_app_config
node_controllers -->|"renders"| node_upload_ui
node_controllers -->|"document operations"| node_document_service
node_admin -->|"admin operations"| node_document_service
node_admin -->|"ingestion stats"| node_statistics
node_document_service -->|"stores files"| node_storage
node_storage -->|"reads and writes"| node_files
node_document_service -->|"persists metadata"| node_document_repo
node_document_repo -->|"maps"| node_knowledge_document
node_document_service -->|"publishes after upload"| node_upload_event
node_upload_event -.->|"received asynchronously"| node_listener
node_async_config -.->|"configures execution"| node_listener
node_listener -->|"delegates"| node_processor
node_processor -->|"reads content"| node_files
node_processor -->|"chunks and indexes"| node_indexer
node_processor -->|"updates status"| node_document_repo
node_indexer -->|"writes embeddings"| node_vector_store
node_rag_config -.->|"wires provider"| node_indexer
node_rag_config -.->|"wires store"| node_vector_store
node_statistics -->|"reads metrics"| node_document_repo

click node_app "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/Ragmvp1Application.java"
click node_controllers "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/controller/DocumentController.java"
click node_admin "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/controller/AdminController.java"
click node_upload_ui "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/resources/templates/documents/upload.html"
click node_security "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/security/SecurityConfiguration.java"
click node_document_service "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentService.java"
click node_storage "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentStorageService.java"
click node_knowledge_document "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/models/entity/KnowledgeDocument.java"
click node_document_repo "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/repository/KnowledgeDocumentRepository.java"
click node_upload_event "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/models/DocumentUploadedEvent.java"
click node_listener "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionEventListener.java"
click node_processor "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionProcessor.java"
click node_indexer "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/EmbeddingIndexer.java"
click node_statistics "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/StatisticsService.java"
click node_async_config "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/config/AsyncConfiguration.java"
click node_rag_config "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/config/EmbeddingConfiguration.java"
click node_app_config "https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/resources/application.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_controllers,node_admin,node_upload_ui toneBlue
class node_document_service,node_storage,node_files,node_knowledge_document,node_statistics toneAmber
class node_upload_event,node_listener,node_processor,node_indexer,node_vector_store toneMint
class node_app,node_security,node_document_repo,node_async_config,node_rag_config,node_app_config toneRose
```

## Components

### Web & Admin

- [Document controllers](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/controller/DocumentController.java): Spring MVC · Handles upload, list, and document detail requests. · `src/main/java/com/ai/applications/rag/ragmvp1/controller/DocumentController.java`
- [Admin controller](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/controller/AdminController.java): Spring MVC · `src/main/java/com/ai/applications/rag/ragmvp1/controller/AdminController.java`
- [Upload page](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/resources/templates/documents/upload.html): server template · `src/main/resources/templates/documents/upload.html`

### Document Lifecycle

- [Document service](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentService.java): lifecycle service · Coordinates document-facing lifecycle operations. · `src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentService.java`
- [File storage service](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentStorageService.java): storage service · Manages uploaded files rooted under data/uploads. · `src/main/java/com/ai/applications/rag/ragmvp1/service/DocumentStorageService.java`
- **Uploaded files**: local file storage
- [Knowledge document](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/models/entity/KnowledgeDocument.java): persistent entity · Stores document metadata and lifecycle state. · `src/main/java/com/ai/applications/rag/ragmvp1/models/entity/KnowledgeDocument.java`
- [Statistics service](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/StatisticsService.java): admin service · Supplies ingestion statistics. · `src/main/java/com/ai/applications/rag/ragmvp1/service/StatisticsService.java`

### Async Ingestion

- [Document uploaded event](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/models/DocumentUploadedEvent.java): application event · Decouples upload completion from ingestion. · `src/main/java/com/ai/applications/rag/ragmvp1/models/DocumentUploadedEvent.java`
- [Ingestion event listener](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionEventListener.java): async event listener · `src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionEventListener.java`
- [Ingestion processor](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionProcessor.java): ingestion orchestrator · Extracts, chunks, and advances index status. · `src/main/java/com/ai/applications/rag/ragmvp1/service/IngestionProcessor.java`
- [Embedding indexer](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/service/EmbeddingIndexer.java): vector adapter · Boundary for embedding and vector indexing. · `src/main/java/com/ai/applications/rag/ragmvp1/service/EmbeddingIndexer.java`
- **Vector store**: RAG index

### Platform & Persistence

- [Spring Boot app](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/Ragmvp1Application.java): application bootstrap · `src/main/java/com/ai/applications/rag/ragmvp1/Ragmvp1Application.java`
- [Security configuration](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/security/SecurityConfiguration.java): Spring Security · Authenticates database-backed users. · `src/main/java/com/ai/applications/rag/ragmvp1/security/SecurityConfiguration.java`
- [Document repository](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/repository/KnowledgeDocumentRepository.java): Spring Data repository · `src/main/java/com/ai/applications/rag/ragmvp1/repository/KnowledgeDocumentRepository.java`
- [Async configuration](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/config/AsyncConfiguration.java): executor configuration · `src/main/java/com/ai/applications/rag/ragmvp1/config/AsyncConfiguration.java`
- [Embedding/vector configuration](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/java/com/ai/applications/rag/ragmvp1/config/EmbeddingConfiguration.java): integration configuration · Wires embedding and vector-store beans. · `src/main/java/com/ai/applications/rag/ragmvp1/config/EmbeddingConfiguration.java`
- [Application configuration](https://github.com/amitksoftech/rag-mvp1/blob/main/src/main/resources/application.yml): properties · Defines operational wiring and storage/bootstrap settings. · `src/main/resources/application.yml`

## Connections

- Spring Boot app → Document controllers: starts MVC
- Spring Boot app → Security configuration: applies security
- Spring Boot app → Application configuration: loads
- Document controllers → Upload page: renders
- Document controllers → Document service: document operations
- Admin controller → Document service: admin operations
- Admin controller → Statistics service: ingestion stats
- Document service → File storage service: stores files
- File storage service → Uploaded files: reads and writes
- Document service → Document repository: persists metadata
- Document repository → Knowledge document: maps
- Document service → Document uploaded event: publishes after upload
- Document uploaded event → Ingestion event listener: received asynchronously
- Async configuration → Ingestion event listener: configures execution
- Ingestion event listener → Ingestion processor: delegates
- Ingestion processor → Uploaded files: reads content
- Ingestion processor → Embedding indexer: chunks and indexes
- Ingestion processor → Document repository: updates status
- Embedding indexer → Vector store: writes embeddings
- Embedding/vector configuration → Embedding indexer: wires provider
- Embedding/vector configuration → Vector store: wires store
- Statistics service → Document repository: reads metrics