# gokulsystems/retrieval-augmented-generation architecture

> Architecture diagram of the GitHub repository gokulsystems/retrieval-augmented-generation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gokulsystems/retrieval-augmented-generation
- Repository: https://github.com/gokulsystems/retrieval-augmented-generation

## Overview

1. **What this repo is**
   - This is a Python-based retrieval-augmented generation (RAG) pipeline centered on local model inference and document search.
   - The architecture is intentionally lightweight: scripts orchestrate preprocessing, embedding/search, storage, and inference rather than a large framework.

2. **Primary execution entrypoints**
   - `rag_inference.py` at the repo root is the main inference entrypoint.
   - `rag_pipeline_1/main.py` is the pipeline runner for the package implementation.
   - `rag_pipeline_1/fastAPI1.py` suggests an API-facing runtime for serving the pipeline.
   - `search.py` and `rag_pipeline_1/debug_search.py` are auxiliary search/inspection entrypoints.

3. **Core package boundary**
   - The actual implementation lives under `rag_pipeline_1/`.
   - That package is split into three main concerns:
     - `engine/` for document and clinical text processing
     - `database/` for storage management
     - `communication/` for API/model interaction and orchestration

4. **Document ingestion and preprocessing**
   - `engine/pdf_to_ocr.py` indicates a path for converting PDFs into OCR-extracted text.
   - `engine/MedicalReportCleaner.py` is likely the first normalization step for noisy clinical text.
   - `engine/structuring.py` and `engine/fhir.py` indicate downstream transformation into structured clinical data.
   - `engine/fhir_to_chuck.py` likely chunks or segments structured content for retrieval.

5. **Clinical/NLP enrichment layer**
   - `engine/demographics_nlp.py` suggests a specialized text-processing step for extracting demographic entities or patient metadata.
   - This implies the pipeline is not generic document RAG only; it has clinical/report-specific enrichment before indexing or inference.

6. **Embedding and retrieval layer**
   - `rag_pipeline_1/vector_embedding.py` is the embedding generation boundary.
   - `rag_pipeline_1/search_function.py` and top-level `search.py` appear to implement retrieval/query helpers over embedded content.
   - The data flow here is: cleaned/structured text → embeddings → search/retrieval candidates for generation.

7. **Persistence and database management**
   - `rag_pipeline_1/database/databaseServer.py` is the storage backend or service wrapper for persisted records/vectors.
   - `rag_pipeline_1/database/clear_database.py` is operational tooling to reset state, which matters because RAG pipelines often rely on regenerated indexes.
   - `rag_pipeline_1/database/` is therefore the persistence boundary between preprocessing and retrieval.

8. **Inference and orchestration**
   - `rag_inference.py` and `rag_pipeline_1/communication/rag_inference.py` indicate an inference layer that likely coordinates retrieval results with the local model.
   - The README states the project uses local GGUF model artifacts such as `model.gguf` and `adapter.gguf`, so generation is local rather than cloud-hosted.
   - This makes the inference path: user query → retrieval → context assembly → local LLM generation.

9. **API/communication boundary**
   - `rag_pipeline_1/communication/apiLoader.py` suggests integration with an external API or request-loading layer.
   - `rag_pipeline_1/fastAPI1.py` is the likely service boundary for exposing the pipeline over HTTP.
   - `rag_pipeline_1/request.py`, `request2.py`, `request3.py`, and `request4.py` look like manual clients or test harnesses for exercising that API.

10. **Operational and diagnostic scripts**
   - `rag_pipeline_1/testscript.py` and `rag_pipeline_1/debug_search.py` support validation and troubleshooting of retrieval behavior.
   - These scripts are important because RAG systems usually need separate debugging for indexing quality, retrieval quality, and generation quality.

11. **Repository shape and duplication**
   - There are both root-level scripts and package-level equivalents, which suggests the repo evolved from ad hoc experimentation into a more organized package.
   - The presence of `requirements.txt`, `rag_pipeline_1/requirement.txt`, and the misspelled `riquirement.txt` indicates environment capture is partly manual and not fully standardized.

12. **High-level data flow for an architecture diagram**
   - Source documents enter through OCR/PDF processing.
   - Text is cleaned, structured, and possibly mapped into FHIR-like representations.
   - The processed content is chunked and embedded.
   - Embeddings and metadata are stored in the database layer.
   - Queries come through scripts or the API layer.
   - Retrieval selects relevant chunks, and the local GGUF model generates the final answer.

13. **Key architectural boundary to show**
   - The most important split is between:
     - offline/ingestion-time processing: OCR, cleaning, structuring, embedding, persistence
     - online/query-time processing: search, retrieval, prompt assembly, local inference, API response
   - That boundary is the backbone of the repo’s architecture.

Main entry points: [`rag_pipeline_1/main.py`](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/main.py) (Pipeline main), [`rag_pipeline_1/fastAPI1.py`](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/fastAPI1.py) (API server), [`rag_pipeline_1/search_function.py`](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/search_function.py) (Query search), [`rag_pipeline_1/communication/rag_inference.py`](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/communication/rag_inference.py) (Inference core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_rag_inference_py["RAG infer<br/>entrypoint<br/>[rag_inference.py]"]
  node_main_py["Pipeline main<br/>runner<br/>[main.py]"]
  node_fastapi1_py["API server<br/>[fastAPI1.py]"]
  node_search_py["Search tool<br/>entrypoint<br/>[search.py]"]
  node_debug_search_py["Debug search<br/>diagnostic<br/>[debug_search.py]"]
end

subgraph group_pipeline["RAG package"]
end

subgraph group_ingestion["Ingestion"]
  node_pdf_to_ocr_py["PDF OCR<br/>ingest<br/>[pdf_to_ocr.py]"]
  node_medical_report_cleaner_py["Text cleaner<br/>normalizer"]
  node_demographics_nlp_py["Demographics NLP<br/>extractor"]
  node_stucturing_py["Structuring<br/>transform<br/>[stucturing.py]"]
  node_fhir_py["FHIR map<br/>transform<br/>[fhir.py]"]
  node_fhir_to_chuck_py["Chunking<br/>segmenter<br/>[fhir_to_chuck.py]"]
end

subgraph group_retrieval["Retrieval"]
  node_vector_embedding_py["Embeddings<br/>embedder"]
  node_search_function_py["Query search<br/>retrieval<br/>[search_function.py]"]
end

subgraph group_storage["Storage"]
  node_database_server_py[("DB server<br/>storage<br/>[databaseServer.py]")]
  node_clear_database_py["Reset DB<br/>ops<br/>[clear_database.py]"]
end

subgraph group_serving["Serving"]
  node_comm_rag_inference_py["Inference core<br/>orchestrator<br/>[rag_inference.py]"]
  node_api_loader_py["API loader<br/>adapter<br/>[apiLoader.py]"]
  node_request_py["Request client<br/>[request.py]"]
  node_request2_py["Request client 2<br/>[request2.py]"]
  node_request3_py["Request client 3<br/>[request3.py]"]
  node_request4_py["Request client 4<br/>[request4.py]"]
end

node_rag_inference_py -->|"retrieves"| node_search_function_py
node_rag_inference_py -->|"delegates"| node_comm_rag_inference_py
node_main_py -->|"ingests"| node_pdf_to_ocr_py
node_main_py -->|"cleans"| node_medical_report_cleaner_py
node_main_py -->|"extracts"| node_demographics_nlp_py
node_main_py -->|"structures"| node_stucturing_py
node_main_py -->|"maps"| node_fhir_py
node_main_py -->|"chunks"| node_fhir_to_chuck_py
node_main_py -->|"embeds"| node_vector_embedding_py
node_vector_embedding_py -->|"stores"| node_database_server_py
node_search_py -->|"calls"| node_search_function_py
node_debug_search_py -->|"inspects"| node_search_function_py
node_search_function_py -->|"queries"| node_database_server_py
node_comm_rag_inference_py -->|"retrieves"| node_search_function_py
node_comm_rag_inference_py -->|"loads"| node_api_loader_py
node_fastapi1_py -->|"serves"| node_api_loader_py
node_request_py -->|"invokes"| node_fastapi1_py
node_request2_py -->|"invokes"| node_fastapi1_py
node_request3_py -->|"invokes"| node_fastapi1_py
node_request4_py -->|"invokes"| node_fastapi1_py
node_clear_database_py -->|"resets"| node_database_server_py
node_comm_rag_inference_py -->|"reads"| node_database_server_py

click node_rag_inference_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_inference.py"
click node_main_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/main.py"
click node_fastapi1_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/fastAPI1.py"
click node_search_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/search.py"
click node_debug_search_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/debug_search.py"
click node_comm_rag_inference_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/communication/rag_inference.py"
click node_api_loader_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/communication/apiLoader.py"
click node_pdf_to_ocr_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/pdf_to_ocr.py"
click node_medical_report_cleaner_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/MedicalReportCleaner.py"
click node_demographics_nlp_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/demographics_nlp.py"
click node_stucturing_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/stucturing.py"
click node_fhir_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/fhir.py"
click node_fhir_to_chuck_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/fhir_to_chuck.py"
click node_vector_embedding_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/vector_embedding.py"
click node_search_function_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/search_function.py"
click node_database_server_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/database/databaseServer.py"
click node_clear_database_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/database/clear_database.py"
click node_request_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request.py"
click node_request2_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request2.py"
click node_request3_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request3.py"
click node_request4_py "https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request4.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_rag_inference_py,node_main_py,node_fastapi1_py,node_search_py,node_debug_search_py toneBlue
class node_pdf_to_ocr_py,node_medical_report_cleaner_py,node_demographics_nlp_py,node_stucturing_py,node_fhir_py,node_fhir_to_chuck_py toneMint
class node_vector_embedding_py,node_search_function_py toneRose
class node_database_server_py,node_clear_database_py toneIndigo
class node_comm_rag_inference_py,node_api_loader_py,node_request_py,node_request2_py,node_request3_py,node_request4_py toneTeal
```

## Components

### Entry points

Top-level scripts and service runners

- [RAG infer](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_inference.py): entrypoint · Root-level inference entrypoint · `rag_inference.py`
- [Pipeline main](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/main.py): runner · Package pipeline runner · `rag_pipeline_1/main.py`
- [API server](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/fastAPI1.py): service · HTTP-facing runtime for the pipeline · `rag_pipeline_1/fastAPI1.py`
- [Search tool](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/search.py): entrypoint · Root-level search helper · `search.py`
- [Debug search](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/debug_search.py): diagnostic · Search inspection script · `rag_pipeline_1/debug_search.py`

### Ingestion

Document processing and enrichment before indexing

- [PDF OCR](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/pdf_to_ocr.py): ingest · PDF to OCR text conversion · `rag_pipeline_1/engine/pdf_to_ocr.py`
- [Text cleaner](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/MedicalReportCleaner.py): normalizer · Clinical text cleanup and normalization · `rag_pipeline_1/engine/MedicalReportCleaner.py`
- [Demographics NLP](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/demographics_nlp.py): extractor · Clinical entity and metadata extraction · `rag_pipeline_1/engine/demographics_nlp.py`
- [Structuring](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/stucturing.py): transform · Transforms cleaned text into structured form · `rag_pipeline_1/engine/stucturing.py`
- [FHIR map](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/fhir.py): transform · FHIR-oriented representation step · `rag_pipeline_1/engine/fhir.py`
- [Chunking](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/engine/fhir_to_chuck.py): segmenter · Segments structured content for retrieval · `rag_pipeline_1/engine/fhir_to_chuck.py`

### Retrieval

Embedding, search, and query-time helpers

- [Embeddings](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/vector_embedding.py): embedder · Generates vector embeddings for indexed content · `rag_pipeline_1/vector_embedding.py`
- [Query search](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/search_function.py): retrieval · Search and retrieval helpers over embedded content · `rag_pipeline_1/search_function.py`

### Storage

Persistence and database management

- [DB server](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/database/databaseServer.py): storage · Persistence backend or service wrapper · `rag_pipeline_1/database/databaseServer.py`
- [Reset DB](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/database/clear_database.py): ops · Database reset and cleanup utility · `rag_pipeline_1/database/clear_database.py`

### Serving

API and inference orchestration

- [Inference core](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/communication/rag_inference.py): orchestrator · Package-level retrieval-to-generation orchestration · `rag_pipeline_1/communication/rag_inference.py`
- [API loader](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/communication/apiLoader.py): adapter · External API/request integration boundary · `rag_pipeline_1/communication/apiLoader.py`
- [Request client](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request.py): client · Manual API exercise script · `rag_pipeline_1/request.py`
- [Request client 2](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request2.py): client · Manual API exercise script · `rag_pipeline_1/request2.py`
- [Request client 3](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request3.py): client · Manual API exercise script · `rag_pipeline_1/request3.py`
- [Request client 4](https://github.com/gokulsystems/retrieval-augmented-generation/blob/master/rag_pipeline_1/request4.py): client · Manual API exercise script · `rag_pipeline_1/request4.py`

## Connections

- RAG infer → Query search: retrieves · Inference uses retrieval results as context
- RAG infer → Inference core: delegates · Root inference entrypoint delegates to package orchestration
- Pipeline main → PDF OCR: ingests · Pipeline starts with document OCR/input normalization
- Pipeline main → Text cleaner: cleans · Normalizes noisy clinical text
- Pipeline main → Demographics NLP: extracts · Adds clinical metadata enrichment
- Pipeline main → Structuring: structures · Builds structured intermediate records
- Pipeline main → FHIR map: maps · Converts structured content into FHIR-like form
- Pipeline main → Chunking: chunks · Segments structured content for indexing
- Pipeline main → Embeddings: embeds · Creates embeddings from processed chunks
- Embeddings → DB server: stores · Persists vectors and metadata
- Search tool → Query search: calls · Root search script uses shared retrieval helpers
- Debug search → Query search: inspects · Debug tooling exercises retrieval behavior
- Query search → DB server: queries · Retrieval reads from persisted index/state
- Inference core → Query search: retrieves · Orchestrator fetches relevant chunks
- Inference core → API loader: loads · Orchestrator integrates with API/request boundary
- API server → API loader: serves · HTTP service exposes request handling
- Request client → API server: invokes · Manual client exercises the API service
- Request client 2 → API server: invokes · Manual client exercises the API service
- Request client 3 → API server: invokes · Manual client exercises the API service
- Request client 4 → API server: invokes · Manual client exercises the API service
- Reset DB → DB server: resets · Operational script clears persisted state
- Inference core → DB server: reads · Inference path may access stored context or metadata
