# mia-platform/ai-rag-template architecture

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

- Interactive diagram: https://gitdiagram.com/mia-platform/ai-rag-template
- Repository: https://github.com/mia-platform/ai-rag-template

## Overview

This backend serves RAG chat and document ingestion. Chat requests enter the API, retrieve similar MongoDB Atlas documents, and pass query, history, and context through the assistant chain to an LLM; ingestion accepts URLs or uploaded files, parses and chunks text, then writes embeddings to the vector store. It also exposes operational health and Prometheus metrics, and updates the vector index at startup. The README documents these capabilities; some implementation details are unsampled, so their internal links are omitted.

Main entry points: [`src/app.py`](https://github.com/mia-platform/ai-rag-template/blob/main/src/app.py) (FastAPI application), [`src/application/assistant/assistant_service.py`](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/assistant_service.py) (Assistant service), [`src/application/embeddings/embedding_service.py`](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/embedding_service.py) (Embedding service), [`src/api/controllers/embeddings/embeddings_handler.py`](https://github.com/mia-platform/ai-rag-template/blob/main/src/api/controllers/embeddings/embeddings_handler.py) (Embedding endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and operations"]
  node_app["FastAPI application<br/>[app.py]"]
  node_chat_api["Chat endpoint"]
  node_embed_api["Embedding endpoints"]
  node_health["Health endpoints"]
  node_metrics_api["Metrics endpoint<br/>[metrics_handler.py]"]
  node_middleware["Request context"]
end

subgraph group_assistant["RAG chat"]
  node_assistant_service["Assistant service"]
  node_assistant_chain["Assistant chain<br/>[assistant_chain.py]"]
  node_prompt["Prompt builder"]
  node_combine["Document combine chain"]
  node_retriever["Vector retriever<br/>[retriever_chain.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_ingest_service["Embedding service"]
  node_parser["File parser<br/>[file_parser.py]"]
  node_chunker["Document chunker"]
  node_links["Hyperlink parser"]
  node_vector_index["Vector index updater"]
end

subgraph group_infra["Models and infrastructure"]
  node_context["Application context<br/>[context.py]"]
  node_config["Service configuration<br/>[service_model.py]"]
  node_config_loader["Configuration loader<br/>[configuration.py]"]
  node_embed_manager["Embedding provider"]
  node_llm_manager["LLM provider<br/>[llm_manager.py]"]
  node_metrics["Prometheus metrics<br/>[metrics_manager.py]"]
end

node_user(("Chat or ingest client"))
node_vector_store[("MongoDB Atlas vector store")]
node_llm_api["LLM API"]
node_web["Website"]
node_file["Uploaded documents"]

node_user -->|"sends requests"| node_app
node_app -->|"registers route"| node_chat_api
node_app -->|"registers route"| node_embed_api
node_app -->|"registers routes"| node_health
node_app -->|"registers route"| node_metrics_api
node_app -->|"installs"| node_middleware
node_chat_api -->|"invokes"| node_assistant_service
node_assistant_service -->|"invokes"| node_assistant_chain
node_assistant_service -->|"configures"| node_retriever
node_assistant_service -->|"builds prompt"| node_prompt
node_assistant_service -->|"configures"| node_combine
node_assistant_service -->|"creates model"| node_llm_manager
node_assistant_chain -->|"retrieves documents"| node_retriever
node_retriever -->|"similarity searches"| node_vector_store
node_assistant_service -->|"returns references"| node_vector_store
node_llm_manager -.->|"calls model"| node_llm_api
node_embed_api -->|"starts generation"| node_ingest_service
node_embed_api -->|"parses upload"| node_parser
node_ingest_service -->|"chunks text"| node_chunker
node_ingest_service -->|"extracts links"| node_links
node_ingest_service -->|"creates embeddings"| node_embed_manager
node_embed_manager -.->|"writes vectors"| node_vector_store
node_ingest_service -->|"stores documents"| node_vector_store
node_web -->|"provides pages"| node_ingest_service
node_file -->|"uploads content"| node_embed_api
node_app -->|"updates index"| node_vector_index
node_vector_index -->|"creates or updates index"| node_vector_store
node_app -->|"loads configuration"| node_config_loader
node_config_loader -->|"validates configuration"| node_config
node_app -->|"creates context"| node_context
node_middleware -->|"provides request context"| node_context
node_metrics_api -->|"exposes metrics"| node_metrics

click node_app "https://github.com/mia-platform/ai-rag-template/blob/main/src/app.py"
click node_chat_api "https://github.com/mia-platform/ai-rag-template/blob/main/src/api/controllers/chat_completions/chat_completions_handler.py"
click node_embed_api "https://github.com/mia-platform/ai-rag-template/blob/main/src/api/controllers/embeddings/embeddings_handler.py"
click node_health "https://github.com/mia-platform/ai-rag-template/tree/main/src/api/controllers/core"
click node_metrics_api "https://github.com/mia-platform/ai-rag-template/blob/main/src/api/controllers/core/metrics/metrics_handler.py"
click node_middleware "https://github.com/mia-platform/ai-rag-template/blob/main/src/api/middlewares/app_context_middleware.py"
click node_assistant_service "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/assistant_service.py"
click node_assistant_chain "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/assistant_chain.py"
click node_prompt "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/assistant_prompt.py"
click node_combine "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/combine_docs_chain.py"
click node_retriever "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/retriever_chain.py"
click node_ingest_service "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/embedding_service.py"
click node_parser "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/file_parser/file_parser.py"
click node_chunker "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/document_chunker.py"
click node_links "https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/hyperlink_parser.py"
click node_vector_index "https://github.com/mia-platform/ai-rag-template/blob/main/src/lib/vector_search_index_updater.py"
click node_context "https://github.com/mia-platform/ai-rag-template/blob/main/src/context.py"
click node_config "https://github.com/mia-platform/ai-rag-template/blob/main/src/configurations/service_model.py"
click node_config_loader "https://github.com/mia-platform/ai-rag-template/blob/main/src/configurations/configuration.py"
click node_embed_manager "https://github.com/mia-platform/ai-rag-template/blob/main/src/infrastracture/embeddings_manager/embeddings_manager.py"
click node_llm_manager "https://github.com/mia-platform/ai-rag-template/blob/main/src/infrastracture/llm_manager/llm_manager.py"
click node_metrics "https://github.com/mia-platform/ai-rag-template/blob/main/src/infrastracture/metrics_manager/metrics_manager.py"

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_app,node_chat_api,node_embed_api,node_health,node_metrics_api,node_middleware,node_user toneBlue
class node_assistant_service,node_assistant_chain,node_prompt,node_combine,node_retriever,node_vector_store toneAmber
class node_ingest_service,node_parser,node_chunker,node_links,node_vector_index,node_llm_api toneMint
class node_context,node_config,node_config_loader,node_embed_manager,node_llm_manager,node_metrics toneRose
class node_web,node_file toneIndigo
```

## Components

### API and operations

- [FastAPI application](https://github.com/mia-platform/ai-rag-template/blob/main/src/app.py): `src/app.py`
- [Chat endpoint](https://github.com/mia-platform/ai-rag-template/blob/main/src/api/controllers/chat_completions/chat_completions_handler.py): `src/api/controllers/chat_completions/chat_completions_handler.py`
- [Embedding endpoints](https://github.com/mia-platform/ai-rag-template/blob/main/src/api/controllers/embeddings/embeddings_handler.py): `src/api/controllers/embeddings/embeddings_handler.py`
- [Health endpoints](https://github.com/mia-platform/ai-rag-template/tree/main/src/api/controllers/core): `src/api/controllers/core`
- [Metrics endpoint](https://github.com/mia-platform/ai-rag-template/blob/main/src/api/controllers/core/metrics/metrics_handler.py): `src/api/controllers/core/metrics/metrics_handler.py`
- [Request context](https://github.com/mia-platform/ai-rag-template/blob/main/src/api/middlewares/app_context_middleware.py): `src/api/middlewares/app_context_middleware.py`

### RAG chat

- [Assistant service](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/assistant_service.py): `src/application/assistant/assistant_service.py`
- [Assistant chain](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/assistant_chain.py): `src/application/assistant/chains/assistant_chain.py`
- [Prompt builder](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/assistant_prompt.py): `src/application/assistant/chains/assistant_prompt.py`
- [Document combine chain](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/combine_docs_chain.py): `src/application/assistant/chains/combine_docs_chain.py`
- [Vector retriever](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/assistant/chains/retriever_chain.py): `src/application/assistant/chains/retriever_chain.py`

### Document ingestion

- [Embedding service](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/embedding_service.py): `src/application/embeddings/embedding_service.py`
- [File parser](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/file_parser/file_parser.py): `src/application/embeddings/file_parser/file_parser.py`
- [Document chunker](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/document_chunker.py): `src/application/embeddings/document_chunker.py`
- [Hyperlink parser](https://github.com/mia-platform/ai-rag-template/blob/main/src/application/embeddings/hyperlink_parser.py): `src/application/embeddings/hyperlink_parser.py`
- [Vector index updater](https://github.com/mia-platform/ai-rag-template/blob/main/src/lib/vector_search_index_updater.py): `src/lib/vector_search_index_updater.py`

### Models and infrastructure

- [Application context](https://github.com/mia-platform/ai-rag-template/blob/main/src/context.py): `src/context.py`
- [Service configuration](https://github.com/mia-platform/ai-rag-template/blob/main/src/configurations/service_model.py): `src/configurations/service_model.py`
- [Configuration loader](https://github.com/mia-platform/ai-rag-template/blob/main/src/configurations/configuration.py): `src/configurations/configuration.py`
- [Embedding provider](https://github.com/mia-platform/ai-rag-template/blob/main/src/infrastracture/embeddings_manager/embeddings_manager.py): `src/infrastracture/embeddings_manager/embeddings_manager.py`
- [LLM provider](https://github.com/mia-platform/ai-rag-template/blob/main/src/infrastracture/llm_manager/llm_manager.py): `src/infrastracture/llm_manager/llm_manager.py`
- [Prometheus metrics](https://github.com/mia-platform/ai-rag-template/blob/main/src/infrastracture/metrics_manager/metrics_manager.py): `src/infrastracture/metrics_manager/metrics_manager.py`

### Other components

- **Chat or ingest client**
- **MongoDB Atlas vector store**
- **LLM API**
- **Website**
- **Uploaded documents**

## Connections

- Chat or ingest client → FastAPI application: sends requests (evidence: `README.md`)
- FastAPI application → Chat endpoint: registers route (evidence: `src/app.py`)
- FastAPI application → Embedding endpoints: registers route (evidence: `src/app.py`)
- FastAPI application → Health endpoints: registers routes (evidence: `src/app.py`)
- FastAPI application → Metrics endpoint: registers route (evidence: `src/app.py`)
- FastAPI application → Request context: installs (evidence: `src/app.py`)
- Chat endpoint → Assistant service: invokes (evidence: `src/api/controllers/chat_completions/chat_completions_handler.py`)
- Assistant service → Assistant chain: invokes (evidence: `src/application/assistant/assistant_service.py`)
- Assistant service → Vector retriever: configures (evidence: `src/application/assistant/assistant_service.py`)
- Assistant service → Prompt builder: builds prompt (evidence: `src/application/assistant/assistant_service.py`)
- Assistant service → Document combine chain: configures (evidence: `src/application/assistant/assistant_service.py`)
- Assistant service → LLM provider: creates model (evidence: `src/application/assistant/assistant_service.py`)
- Assistant chain → Vector retriever: retrieves documents (evidence: `src/application/assistant/chains/assistant_chain.py`)
- Vector retriever → MongoDB Atlas vector store: similarity searches (evidence: `src/application/assistant/chains/retriever_chain.py`)
- Assistant service → MongoDB Atlas vector store: returns references (evidence: `README.md`)
- LLM provider → LLM API: calls model
- Embedding endpoints → Embedding service: starts generation (evidence: `src/api/controllers/embeddings/embeddings_handler.py`)
- Embedding endpoints → File parser: parses upload (evidence: `src/api/controllers/embeddings/embeddings_handler.py`)
- Embedding service → Document chunker: chunks text (evidence: `src/application/embeddings/embedding_service.py`)
- Embedding service → Hyperlink parser: extracts links (evidence: `src/application/embeddings/embedding_service.py`)
- Embedding service → Embedding provider: creates embeddings (evidence: `src/application/embeddings/embedding_service.py`)
- Embedding provider → MongoDB Atlas vector store: writes vectors
- Embedding service → MongoDB Atlas vector store: stores documents (evidence: `src/application/embeddings/embedding_service.py`)
- Website → Embedding service: provides pages (evidence: `README.md`)
- Uploaded documents → Embedding endpoints: uploads content (evidence: `README.md`)
- FastAPI application → Vector index updater: updates index (evidence: `src/app.py`)
- Vector index updater → MongoDB Atlas vector store: creates or updates index (evidence: `README.md`)
- FastAPI application → Configuration loader: loads configuration (evidence: `src/app.py`)
- Configuration loader → Service configuration: validates configuration (evidence: `src/configurations/configuration.py`)
- FastAPI application → Application context: creates context (evidence: `src/app.py`)
- Request context → Application context: provides request context (evidence: `src/api/middlewares/app_context_middleware.py`)
- Metrics endpoint → Prometheus metrics: exposes metrics (evidence: `src/api/controllers/core/metrics/metrics_handler.py`)