# suganth1704/rag_app_backend architecture

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

- Interactive diagram: https://gitdiagram.com/suganth1704/rag_app_backend
- Repository: https://github.com/suganth1704/rag_app_backend

## Overview

1. **What this repo is**
   - `RAG_APP` is a retrieval-augmented generation backend: it ingests documents, turns them into embeddings, stores them in a vector database, retrieves relevant chunks for a query, and sends that context to an LLM for answer generation.

2. **Top-level runtime entrypoint**
   - `main.py` is the application bootstrap. It is the likely place where the FastAPI app is created and the API routes are mounted.
   - This is the handoff point from process startup into the request-serving layer.

3. **API boundary**
   - `api/route.py` contains the HTTP endpoints and request handling.
   - `api/schema.py` defines the API contract, likely using Pydantic models for typed input/output payloads.
   - This layer should be treated as thin orchestration: validate requests, call ingestion/retrieval/chat services, return responses.

4. **Ingestion subsystem**
   - `ingestion/ingest.py` is responsible for document processing.
   - Based on the README, the ingestion flow is: load document → chunk text → create embeddings → persist vectors.
   - The chunking settings are part of the architecture: `chunk_size=700`, `chunk_overlap=150`.

5. **Embedding and indexing flow**
   - The README states embeddings are created with `all-MiniLM-L6-v2`.
   - Those embeddings become the durable search index stored in ChromaDB, not the raw documents themselves.
   - This means the key persisted artifact is the vectorized chunk representation plus any associated metadata.

6. **Vector store boundary**
   - `vector_store/chroma_client.py` encapsulates ChromaDB access.
   - This module is the persistence/search boundary for retrieval operations, isolating the rest of the app from Chroma-specific calls.
   - Retrieval uses similarity search and MMR-style selection according to the README, so the vector store is not just storage; it also drives candidate ranking.

7. **LLM / chat subsystem**
   - `llm/groq_client.py` is the integration point to Groq-hosted models.
   - `llm/chat.py` likely composes the prompt, retrieved context, and user query into the final chat response.
   - The model called out in the README is `llama-3.3-70b-versatile`, which is the generation endpoint for the response stage.

8. **End-to-end data flow**
   - Ingestion path: documents enter through the backend, are chunked and embedded, then stored in ChromaDB.
   - Query path: a user query arrives via the API, is embedded, used to retrieve relevant chunks from ChromaDB, and those chunks are passed into the LLM as context.
   - The final answer is returned through the API layer to the client.

9. **Cross-cutting concerns**
   - `config/logging.py` centralizes logging setup, which is important for tracing ingestion, retrieval, and generation failures across the pipeline.
   - `config/__init__.py` suggests additional runtime configuration may be loaded here, likely environment-driven via `.env` as noted in the README.

10. **External dependencies that matter architecturally**
   - FastAPI provides the HTTP interface.
   - ChromaDB is the vector persistence/retrieval engine.
   - Groq is the external model provider for generation.
   - The README also mentions LangChain/LangGraph as orchestration frameworks; even though they are not visible as dedicated modules in the tree, they likely influence how retrieval and prompt workflows are structured.

11. **Likely system boundaries for a diagram**
   - Client/UI → FastAPI API → ingestion or chat orchestration → vector store / LLM service.
   - Persistence is split: vector data in ChromaDB, operational concerns in logs/config, and no relational database layer is present in the tree.

12. **What is not present**
   - There is no dedicated database model layer, task queue, or separate worker service in the repository tree.
   - If Redis is used, it is only mentioned in the README and not represented by a visible module here, so it should be treated as optional auxiliary infrastructure rather than a core subsystem.

Main entry points: [`api/route.py`](https://github.com/suganth1704/rag_app_backend/blob/main/api/route.py) (Routes), [`vector_store/chroma_client.py`](https://github.com/suganth1704/rag_app_backend/blob/main/vector_store/chroma_client.py) (Chroma Client), [`config/__init__.py`](https://github.com/suganth1704/rag_app_backend/blob/main/config/__init__.py) (Config), [`main.py`](https://github.com/suganth1704/rag_app_backend/blob/main/main.py) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>app bootstrap<br/>[main.py]"]
end

subgraph group_api["API"]
  node_route["Routes<br/>http handlers<br/>[route.py]"]
  node_schema["Schemas<br/>payload models<br/>[schema.py]"]
end

subgraph group_ingestion["Ingestion"]
  node_ingest["Ingest<br/>pipeline<br/>[ingest.py]"]
  node_chunking["Chunking<br/>text split"]
  node_embed_model(("Embeddings<br/>embedding model"))
end

subgraph group_retrieval["Retrieval"]
  node_chroma[("Chroma Client<br/>vector store<br/>[chroma_client.py]")]
end

subgraph group_llm["LLM"]
  node_chat["Chat<br/>response orchestration<br/>[chat.py]"]
  node_groq_client["Groq Client<br/>llm client<br/>[groq_client.py]"]
end

subgraph group_support["Support"]
  node_logging["Logging<br/>cross-cutting<br/>[logging.py]"]
  node_config["Config<br/>[__init__.py]"]
end

node_client(("Client<br/>external caller"))
node_chroma_db[("ChromaDB<br/>external storage")]
node_groq_model(("Groq Model<br/>external llm"))

node_client -->|"starts"| node_main
node_main -->|"mounts"| node_route
node_route -->|"validates"| node_schema
node_route -->|"ingests"| node_ingest
node_route -->|"answers"| node_chat
node_ingest -->|"splits"| node_chunking
node_chunking -->|"encodes"| node_embed_model
node_embed_model -->|"writes vectors"| node_chroma
node_chroma -->|"persists"| node_chroma_db
node_route -->|"retrieves"| node_chroma
node_chroma -->|"returns context"| node_chat
node_chat -->|"calls"| node_groq_client
node_groq_client -->|"generates"| node_groq_model
node_logging -.->|"traces"| node_main
node_logging -.->|"traces"| node_ingest
node_logging -.->|"traces"| node_chat
node_config -.->|"configures"| node_main
node_config -.->|"configures"| node_ingest
node_config -.->|"configures"| node_chroma
node_config -.->|"configures"| node_groq_client

click node_main "https://github.com/suganth1704/rag_app_backend/blob/main/main.py"
click node_route "https://github.com/suganth1704/rag_app_backend/blob/main/api/route.py"
click node_schema "https://github.com/suganth1704/rag_app_backend/blob/main/api/schema.py"
click node_ingest "https://github.com/suganth1704/rag_app_backend/blob/main/ingestion/ingest.py"
click node_chroma "https://github.com/suganth1704/rag_app_backend/blob/main/vector_store/chroma_client.py"
click node_chat "https://github.com/suganth1704/rag_app_backend/blob/main/llm/chat.py"
click node_groq_client "https://github.com/suganth1704/rag_app_backend/blob/main/llm/groq_client.py"
click node_logging "https://github.com/suganth1704/rag_app_backend/blob/main/config/logging.py"
click node_config "https://github.com/suganth1704/rag_app_backend/blob/main/config/__init__.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_main toneBlue
class node_route,node_schema toneAmber
class node_ingest,node_chunking,node_embed_model toneMint
class node_chroma toneRose
class node_chat,node_groq_client toneIndigo
class node_logging,node_config toneTeal
class node_client,node_chroma_db,node_groq_model toneNeutral
```

## Components

### Runtime

Application bootstrap and request entrypoint

- [Main](https://github.com/suganth1704/rag_app_backend/blob/main/main.py): app bootstrap · Starts the backend and mounts the application routes · `main.py`

### API

HTTP request/response boundary

- [Routes](https://github.com/suganth1704/rag_app_backend/blob/main/api/route.py): http handlers · API endpoints and request orchestration · `api/route.py`
- [Schemas](https://github.com/suganth1704/rag_app_backend/blob/main/api/schema.py): payload models · Typed request and response contracts · `api/schema.py`

### Ingestion

Document processing and indexing pipeline

- [Ingest](https://github.com/suganth1704/rag_app_backend/blob/main/ingestion/ingest.py): pipeline · Loads, chunks, embeds, and indexes documents · `ingestion/ingest.py`
- **Chunking**: text split · Splits documents with configured chunk size and overlap
- **Embeddings**: embedding model · all-MiniLM-L6-v2 vectorizer used to encode chunks

### Retrieval

Vector search and persistence boundary

- [Chroma Client](https://github.com/suganth1704/rag_app_backend/blob/main/vector_store/chroma_client.py): vector store · Encapsulates vector persistence and similarity/MMR retrieval · `vector_store/chroma_client.py`

### LLM

Prompt assembly and model integration

- [Chat](https://github.com/suganth1704/rag_app_backend/blob/main/llm/chat.py): response orchestration · Builds prompt, injects retrieved context, and produces answers · `llm/chat.py`
- [Groq Client](https://github.com/suganth1704/rag_app_backend/blob/main/llm/groq_client.py): llm client · Integration wrapper for hosted model calls · `llm/groq_client.py`

### Support

Configuration and logging

- [Logging](https://github.com/suganth1704/rag_app_backend/blob/main/config/logging.py): cross-cutting · Centralized logging setup for runtime and pipeline tracing · `config/logging.py`
- [Config](https://github.com/suganth1704/rag_app_backend/blob/main/config/__init__.py): runtime config · Shared application configuration and environment loading · `config/__init__.py`

### Other components

- **Client**: external caller · User or upstream service that sends queries and documents
- **ChromaDB**: external storage · Vector database holding embedded chunks and metadata
- **Groq Model**: external llm · llama-3.3-70b-versatile generation endpoint

## Connections

- Client → Main: starts · Client request enters the application process
- Main → Routes: mounts · Bootstrap hands off to HTTP routes
- Routes → Schemas: validates · Endpoints use typed request and response models
- Routes → Ingest: ingests · API can trigger document ingestion
- Routes → Chat: answers · API can trigger retrieval-augmented chat
- Ingest → Chunking: splits · Documents are chunked before embedding
- Chunking → Embeddings: encodes · Chunks are converted into embeddings
- Embeddings → Chroma Client: writes vectors · Embeddings and metadata are stored for retrieval
- Chroma Client → ChromaDB: persists · Chroma client delegates storage and search to ChromaDB
- Routes → Chroma Client: retrieves · Query handling fetches relevant chunks from the vector store
- Chroma Client → Chat: returns context · Retrieved chunks are passed into response generation
- Chat → Groq Client: calls · Chat orchestration delegates model execution
- Groq Client → Groq Model: generates · Hosted Groq model produces the final answer
- Logging → Main: traces · Shared logging is used during app startup
- Logging → Ingest: traces · Ingestion failures and progress are logged
- Logging → Chat: traces · Retrieval and generation events are logged
- Config → Main: configures · Runtime settings are loaded into the app
- Config → Ingest: configures · Chunking and pipeline settings are sourced from config
- Config → Chroma Client: configures · Vector store connection details are sourced from config
- Config → Groq Client: configures · Model/provider credentials and parameters are sourced from config