# mr-rsr/agentic-rag-app-tutorial architecture

> Architecture diagram of the GitHub repository mr-rsr/agentic-rag-app-tutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-rsr/agentic-rag-app-tutorial
- Repository: https://github.com/mr-rsr/agentic-rag-app-tutorial

## Overview

1. **Top-level shape**
   - This is a small, service-oriented **FastAPI backend** for a RAG agent.
   - The runtime entrypoint is `app/main.py`, with most behavior pushed into `app/services/*` rather than living in the API layer.

2. **API boundary**
   - The HTTP layer exposes three main operations: **ingest**, **query**, and **health**.
   - `app/models/schemas.py` defines the request/response contracts, so the API boundary is explicit and typed.

3. **Configuration boundary**
   - `app/config/settings.py` centralizes environment-driven configuration.
   - The repo is designed to run locally with `.env` values such as AWS credentials, Gemini API key, and the PDF folder path; this makes external integrations configurable without changing code.

4. **Document ingestion subsystem**
   - `app/services/document_loader.py` is the intake path for content.
   - It supports two sources: **web URLs** and **PDF files** from `pdf_docs/`.
   - This layer is responsible for loading, cleaning, and splitting content into chunks suitable for retrieval.

5. **Embedding and model subsystem**
   - `app/services/models.py` owns creation of the LLM and embedding model instances.
   - The README indicates the primary stack is **AWS Bedrock** for Claude Haiku + Titan embeddings, with **Google Gemini** as an optional alternative.
   - This is the main model boundary between business logic and external AI providers.

6. **Vector storage subsystem**
   - `app/services/vector_store.py` wraps a **FAISS** index.
   - Ingestion produces embedded chunks that are stored here for similarity search, making this the retrieval backbone of the RAG flow.

7. **Agent/tooling subsystem**
   - `app/services/tools.py` defines the tools the agent can invoke.
   - The tool set includes:
     - **RAG retrieval** over the vector store
     - **Web search** via DuckDuckGo
     - **Weather** via a mock tool
   - This layer is where the agent gets access to non-LLM capabilities.

8. **Orchestration layer**
   - `app/services/agent.py` coordinates the LLM and the available tools into a single query-handling agent.
   - It sits above retrieval and tool execution, and below the API, acting as the main business-logic orchestrator.

9. **Primary data flow: ingestion**
   - A client calls `/ingest` with either a URL or a request to process the PDF folder.
   - Documents are loaded and split, embedded with the configured embedding model, then written into FAISS.
   - The response reports how many chunks were added and from which source(s).

10. **Primary data flow: question answering**
    - A client calls `/query` with a natural-language prompt.
    - The agent decides whether to answer from retrieved context, web search, weather, or a combination.
    - The final response is synthesized by the LLM and returned through the API.

11. **Persistence and state**
    - The architecture appears centered on an **in-process vector store** rather than a separate database service.
    - The `pdf_docs/` directory is effectively a local content source, and the FAISS index is the key stateful component supporting retrieval.

12. **External dependencies that shape the design**
    - The system depends on **FastAPI/Uvicorn** for serving, **FAISS** for retrieval, and external model/search providers for live intelligence.
    - DuckDuckGo search adds real-time web grounding, while the weather tool provides an additional non-retrieval capability for the agent.

13. **How to draw the architecture**
    - A clear diagram would show: **client → FastAPI routes → service layer → (document loader / agent / tools / vector store / model factory)**.
    - External boxes should include **AWS Bedrock**, **Gemini**, and **DuckDuckGo**.
    - The `pdf_docs/` folder should be shown as a local input source feeding ingestion, and FAISS as the local retrieval store feeding the agent.

Main entry points: [`app/main.py`](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/main.py) (FastAPI app), [`app/services/models.py`](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/models.py) (Models), [`app/services/agent.py`](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/agent.py) (Agent), [`app/services/vector_store.py`](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/vector_store.py) (Vector store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API layer"]
  node_client(("Client<br/>caller"))
  node_main["FastAPI app<br/>entrypoint<br/>[main.py]"]
  node_ingest_api["Ingest<br/>endpoint"]
  node_query_api["Query<br/>endpoint"]
  node_health_api["Health<br/>endpoint"]
  node_schemas["Schemas<br/>contracts<br/>[schemas.py]"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
end

subgraph group_services["Service layer"]
  node_loader["Loader<br/>ingestion<br/>[document_loader.py]"]
  node_model_factory["Models<br/>model factory<br/>[models.py]"]
  node_vector_store[("Vector store<br/>retrieval store<br/>[vector_store.py]")]
  node_tools{{"Tools<br/>tooling<br/>[tools.py]"}}
  node_agent["Agent<br/>orchestrator<br/>[agent.py]"]
end

subgraph group_runtime["State and sources"]
  node_pdf_docs["PDF docs<br/>local source"]
  node_faiss[("FAISS<br/>index")]
  node_bedrock(("AWS Bedrock<br/>llm provider"))
  node_gemini(("Gemini<br/>llm provider"))
  node_duckduckgo(("DuckDuckGo<br/>search provider"))
end

node_client -->|"calls"| node_main
node_main -->|"exposes"| node_ingest_api
node_main -->|"exposes"| node_query_api
node_main -->|"exposes"| node_health_api
node_main -->|"uses"| node_schemas
node_main -->|"loads"| node_settings
node_ingest_api -->|"loads"| node_loader
node_ingest_api -->|"embeds"| node_model_factory
node_ingest_api -->|"indexes"| node_vector_store
node_loader -->|"reads"| node_pdf_docs
node_loader -->|"prepares"| node_model_factory
node_model_factory -->|"primary"| node_bedrock
node_model_factory -.->|"optional"| node_gemini
node_vector_store -->|"wraps"| node_faiss
node_query_api -->|"delegates"| node_agent
node_agent -->|"invokes"| node_tools
node_agent -->|"runs on"| node_model_factory
node_tools -->|"retrieves"| node_vector_store
node_tools -->|"searches"| node_duckduckgo
node_agent -.->|"grounds"| node_vector_store

click node_main "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/main.py"
click node_schemas "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/models/schemas.py"
click node_settings "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/config/settings.py"
click node_loader "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/document_loader.py"
click node_model_factory "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/models.py"
click node_vector_store "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/vector_store.py"
click node_tools "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/tools.py"
click node_agent "https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/agent.py"
click node_pdf_docs "https://github.com/mr-rsr/agentic-rag-app-tutorial/tree/main/pdf_docs"

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_client,node_main,node_ingest_api,node_query_api,node_health_api,node_schemas,node_settings toneBlue
class node_loader,node_model_factory,node_vector_store,node_tools,node_agent toneAmber
class node_pdf_docs,node_faiss,node_bedrock,node_gemini,node_duckduckgo toneMint
```

## Components

### API layer

FastAPI entrypoint, contracts, and request handlers.

- **Client**: caller · HTTP consumer of ingest and query operations.
- [FastAPI app](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/main.py): entrypoint · Runtime entrypoint that exposes the HTTP API. · `app/main.py`
- **Ingest**: endpoint · API operation for loading and indexing content.
- **Query**: endpoint · API operation for answering natural-language questions.
- **Health**: endpoint · Lightweight service health check.
- [Schemas](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/models/schemas.py): contracts · Typed request and response models for the API. · `app/models/schemas.py`
- [Settings](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/config/settings.py): config · Environment-driven application configuration. · `app/config/settings.py`

### Service layer

Core ingestion, retrieval, model, and agent orchestration services.

- [Loader](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/document_loader.py): ingestion · Loads, cleans, and splits web or PDF documents into chunks. · `app/services/document_loader.py`
- [Models](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/models.py): model factory · Creates the LLM and embedding model instances. · `app/services/models.py`
- [Vector store](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/vector_store.py): retrieval store · Wraps FAISS for similarity search over embedded chunks. · `app/services/vector_store.py`
- [Tools](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/tools.py): tooling · Agent tools for retrieval, web search, and weather. · `app/services/tools.py`
- [Agent](https://github.com/mr-rsr/agentic-rag-app-tutorial/blob/main/app/services/agent.py): orchestrator · Coordinates the model and tools to answer queries. · `app/services/agent.py`

### State and sources

Local content and retrieval state used by the app.

- [PDF docs](https://github.com/mr-rsr/agentic-rag-app-tutorial/tree/main/pdf_docs): local source · Local folder containing PDF inputs for ingestion. · `pdf_docs`
- **FAISS**: index · Local similarity index backing retrieval.
- **AWS Bedrock**: llm provider · Primary external provider for Claude and Titan models.
- **Gemini**: llm provider · Optional alternative model provider.
- **DuckDuckGo**: search provider · External web search tool used by the agent.

## Connections

- Client → FastAPI app: calls · Sends HTTP requests to the FastAPI application.
- FastAPI app → Ingest: exposes · Registers the ingest operation.
- FastAPI app → Query: exposes · Registers the query operation.
- FastAPI app → Health: exposes · Registers the health check.
- FastAPI app → Schemas: uses · Shares typed request and response contracts.
- FastAPI app → Settings: loads · Reads runtime configuration from the environment.
- Ingest → Loader: loads · Starts document intake and chunking.
- Ingest → Models: embeds · Builds embeddings for ingested chunks.
- Ingest → Vector store: indexes · Writes embedded chunks into retrieval storage.
- Loader → PDF docs: reads · Consumes local PDF documents when requested.
- Loader → Models: prepares · Produces content ready for embedding and retrieval.
- Models → AWS Bedrock: primary · Uses AWS Bedrock as the default model backend.
- Models → Gemini: optional · Can switch to Gemini as an alternative backend.
- Vector store → FAISS: wraps · FAISS is the underlying similarity index.
- Query → Agent: delegates · Hands natural-language questions to the agent layer.
- Agent → Tools: invokes · Uses tool capabilities during reasoning.
- Agent → Models: runs on · Relies on the configured LLM for synthesis.
- Tools → Vector store: retrieves · Exposes RAG retrieval over embedded chunks.
- Tools → DuckDuckGo: searches · Uses web search for fresh context.
- Agent → Vector store: grounds · Retrieval can feed the final answer path.