# omkanekar28/rag-implementation architecture

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

- Interactive diagram: https://gitdiagram.com/omkanekar28/rag-implementation
- Repository: https://github.com/omkanekar28/rag-implementation

## Overview

##### Project type and purpose
- This is a full-stack web application implementing a Retrieval-Augmented Generation (RAG) pipeline for movie recommendation.
- It provides both a command-line interface (CSV-based retrieval and optional LLM-driven explanation) and a Flask web front end for interaction.

##### File structure
Top-level:
- data/ – raw and cleaned CSV datasets
- src/ – all Python modules and Flask app
- requirements.txt, readme.md
- screenshots/ – UI mockups

Inside src/:
- app.py – Flask entry point, routes, UI glue
- config.py – all hard-coded paths and model identifiers
- csv_cleaning.py – raw → cleaned CSV pipeline
- csv_to_faiss.py – builds FAISS index from cleaned CSV
- faiss_store/ – persisted FAISS index and metadata pickle
- recommend_movies.py – pure retrieval using FAISS
- recommend_movies_llm.py – retrieval + LLM reasoning
- prompts.py – templating LLM prompts
- models.py – wrapper for SentenceTransformer embeddings
- static/ + templates/ – web UI assets and HTML

##### Key insights from README
- Two modes: simple FAISS retrieval, and RAG (retrieve + LLM via Hugging Face)
- Tech stack: Python, Flask, FAISS, SentenceTransformers, Hugging Face models
- Modular design: each stage is a separate script/module

##### Main components
A. Data Layer
– Raw CSV (data/movie_dataset.csv)
– Cleaned CSV (data/cleaned_movie_dataset.csv)
– FAISS Index (src/faiss_store/movies.index + metadata pickle)

B. Indexing Pipeline
– csv_cleaning.py → output cleaned CSV
– csv_to_faiss.py → build FAISS index from embeddings

C. Embedding Service
– models.py using SentenceTransformer
– Generates vector representations for documents and queries

D. Retrieval Service
– FAISS index search (recommend_movies.py)
– Returns top-N nearest movie vectors + distances

E. RAG/Generation Service
– prompts.py constructs LLM prompt from query + retrieved docs
– recommend_movies_llm.py calls Hugging Face model via config.py to generate reasoning

F. Web Application
– app.py defines Flask routes:
- “/” → index.html
- “/recommend_movies” → display_results.html
- “/recommend_movies_llm” → display_results_llm.html
– static assets (CSS, images) and Jinja2 templates

G. External Dependencies
– FAISS library for similarity search
– SentenceTransformers for embeddings
– Hugging Face Transformers for LLM inference

##### Relationships & data flow
- Offline: Raw CSV → [csv_cleaning.py] → Cleaned CSV → [csv_to_faiss.py] → FAISS Index
- Online user query:
1. User submits a description + N via web form → Flask route
2. models.py encodes query → vector
3. FAISS index search → top-N results
4a. Simple mode: return titles + distances → display_results.html
4b. RAG mode: combine retrieved docs + user query → prompt → LLM → structured explanation → display_results_llm.html
- Config parameters (model path, index path) come from config.py

##### Architectural patterns & principles
- Layered architecture: Data → Indexing → Retrieval → Generation → Presentation
- Separation of concerns: each major function (clean, index, retrieve, generate, serve) lives in its own module

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Offline Indexing Pipeline"
        RawCSV(("Raw CSV")):::data
        csvClean["csv_cleaning.py"]:::service
        CleanCSV(("Cleaned CSV")):::data
        csvToFaiss["csv_to_faiss.py"]:::service
        faissStore["FAISS Store\n(src/faiss_store)"]:::service
        Index(("FAISS Index")):::data
        Metadata(("FAISS Metadata")):::data

        RawCSV -->|"clean raw CSV"| csvClean -->|"produces cleaned CSV"| CleanCSV -->|"build index"| csvToFaiss -->|"store index & metadata"| faissStore
        faissStore -->|"index file"| Index
        faissStore -->|"metadata pickle"| Metadata
    end

    subgraph "Online Serving Pipeline"
        user["User"]:::external
        app["Flask App\n(app.py)"]:::service

        subgraph "Static Assets"
            styleCss["style.css"]:::service
            images["images"]:::service
        end

        subgraph "HTML Templates"
            base["base.html"]:::service
            indexT["index.html"]:::service
            recMoviesT["recommend_movies.html"]:::service
            displayResT["display_results.html"]:::service
            recLLMT["recommend_movies_llm.html"]:::service
            displayResLLMT["display_results_llm.html"]:::service
        end

        user --> app
        app --> styleCss
        app --> images
        app --> base
        app --> indexT
        app --> recMoviesT
        app --> displayResT
        app --> recLLMT
        app --> displayResLLMT
    end

    subgraph "Retrieval & Generation Services"
        modelsSvc["Embedding Service\n(models.py)"]:::service
        recSimple["Retrieval Service\n(recommend_movies.py)"]:::service
        recRAG["RAG Service\n(recommend_movies_llm.py)"]:::service
        promptsSvc["Prompt Templates\n(prompts.py)"]:::service
        config["Config\n(config.py)"]:::service
    end

    subgraph "External Dependencies"
        faissLib["FAISS"]:::external
        sf["SentenceTransformers"]:::external
        hf["Hugging Face LLM"]:::external
    end

    subgraph "Documentation"
        req["requirements.txt"]:::external
        readme["readme.md"]:::external
    end

    app --> modelsSvc
    modelsSvc --> recSimple
    modelsSvc --> recRAG
    app --> recSimple
    app --> recRAG

    recSimple -->|"loads index"| Index
    recSimple --> faissLib
    recRAG -->|"loads index"| Index
    recRAG --> faissLib

    modelsSvc -->|"loads model"| sf
    recRAG --> promptsSvc --> config --> hf

    click RawCSV "https://github.com/omkanekar28/rag-implementation/blob/main/data/movie_dataset.csv"
    click CleanCSV "https://github.com/omkanekar28/rag-implementation/blob/main/data/cleaned_movie_dataset.csv"
    click Index "https://github.com/omkanekar28/rag-implementation/blob/main/src/faiss_store/movies.index"
    click Metadata "https://github.com/omkanekar28/rag-implementation/blob/main/src/faiss_store/movies_metadata.pkl"
    click faissStore "https://github.com/omkanekar28/rag-implementation/tree/main/src/faiss_store"
    click csvClean "https://github.com/omkanekar28/rag-implementation/blob/main/src/csv_cleaning.py"
    click csvToFaiss "https://github.com/omkanekar28/rag-implementation/blob/main/src/csv_to_faiss.py"
    click modelsSvc "https://github.com/omkanekar28/rag-implementation/blob/main/src/models.py"
    click recSimple "https://github.com/omkanekar28/rag-implementation/blob/main/src/recommend_movies.py"
    click recRAG "https://github.com/omkanekar28/rag-implementation/blob/main/src/recommend_movies_llm.py"
    click promptsSvc "https://github.com/omkanekar28/rag-implementation/blob/main/src/prompts.py"
    click config "https://github.com/omkanekar28/rag-implementation/blob/main/src/config.py"
    click app "https://github.com/omkanekar28/rag-implementation/blob/main/src/app.py"
    click styleCss "https://github.com/omkanekar28/rag-implementation/blob/main/src/static/style.css"
    click images "https://github.com/omkanekar28/rag-implementation/tree/main/src/static/images/"
    click base "https://github.com/omkanekar28/rag-implementation/blob/main/src/templates/base.html"
    click indexT "https://github.com/omkanekar28/rag-implementation/blob/main/src/templates/index.html"
    click recMoviesT "https://github.com/omkanekar28/rag-implementation/blob/main/src/templates/recommend_movies.html"
    click displayResT "https://github.com/omkanekar28/rag-implementation/blob/main/src/templates/display_results.html"
    click recLLMT "https://github.com/omkanekar28/rag-implementation/blob/main/src/templates/recommend_movies_llm.html"
    click displayResLLMT "https://github.com/omkanekar28/rag-implementation/blob/main/src/templates/display_results_llm.html"
    click req "https://github.com/omkanekar28/rag-implementation/blob/main/requirements.txt"
    click readme "https://github.com/omkanekar28/rag-implementation/blob/main/readme.md"

    classDef data fill:#ffe4b5,stroke:#ccaa88,stroke-width:1px,shape:cylinder;
    classDef service fill:#bbdefb,stroke:#448aff,stroke-width:1px;
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px,shape:cloud;
```
