# polarbear333/rag-llm-based-recommender architecture

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

- Interactive diagram: https://gitdiagram.com/polarbear333/rag-llm-based-recommender
- Repository: https://github.com/polarbear333/rag-llm-based-recommender

## Overview

##### Project Type & Key Purpose
- This is a full-stack AI-powered e-commerce recommendation system that leverages Retrieval Augmented Generation (RAG), Large Language Models (LLMs), and sentiment analysis.
- It’s built to enhance the shopping experience via semantic search, product recommendation, and contextual content generation.
- It integrates a FastAPI backend with a React/Next.js frontend, uses Google Cloud Platform (GCP) services (BigQuery, Vertex AI, Cloud Storage) and manages infrastructure using Terraform.

##### Analyzing the File Structure
- The top-level directories clearly separate the backend, frontend, and infra:
- Backend: Contains the FastAPI application, API endpoints (e.g., search and sentiment endpoints), core modules (like search, database connectors, LLM integration via Vertex AI), and tests.
- Frontend: Contains a React/Next.js application with components (UI elements, chat interfaces, product cards) and utilities for API communication and theming.
- Infra: Holds Terraform configuration files and supporting infrastructure scripts to deploy the system on GCP.
- Additional directories (bigQuery, etl_full.py) denote SQL scripts for table creation, vector indexing, and data processing scripts (ETL using PySpark).
- There are also supplementary files (e.g., README, package.json, Dockerfiles) that indicate deployment and dependency management practices.

##### Key Components
a. Data Processing Pipeline:
- Data ingestion from the Amazon Reviews dataset.
- ETL processes using PySpark (etl_full.py) to clean data.
- Generation of vector embeddings via Vertex AI.
- Loading and indexing data into BigQuery (including SQL scripts for table creation and vector indexing).
b. Backend API Layer:
- FastAPI service (in the “backend/app/main.py”).
- API endpoints for product search, sentiment analysis (search_endpoints.py & sentiment_endpoints.py).
- Core processing modules handling vector search, RAG pipeline (modules in “backend/app/core”) and database operations (bigquery integration in “backend/app/db”).
- Integration with third-party services such as Vertex AI and ScaNN for vector search.
c. Frontend Web Interface:
- React/Next.js application responsible for displaying the chatbot interface, product recommendations, and dynamic visuals.
- Components for chat (ChatbotInterface, FullPageChat, MaximizedChatbox) and product display (ProductCard, ProductGrid).
- Utility functions used for API calls and theming.
d. Infrastructure & Deployment:
- Terraform scripts (in the infra folder) that set up GCP resources including Cloud Run, BigQuery, Vertex AI, and Cloud Storage.
- Dockerfiles in both the backend and infra directories to containerize services.
- CI/CD configuration in the .github/workflows directory for deployment automation.

##### Relationships & Data Flow
- Data flow from the ETL process to BigQuery (data ingestion and vector embedding generation).
- Communication between the FastAPI backend and BigQuery, Vertex AI for query processing and recommendation generation.
- API interaction between the Next.js frontend and the backend service.
- Infrastructure provisioning from Terraform to all deployed components on GCP.
- Use annotations to represent synchronous API calls, asynchronous processing, and streaming data (if applicable).

##### Architectural Patterns & Design Principles
- Microservices architecture:
- Separate services (backend API, frontend client, data pipeline, infrastructure provisioning) that can scale independently.
- Use of RAG (Retrieval Augmented Generation) and vector search:
- Modular divisions (e.g., separating core services like search, sentiment analysis, and helper utilities).

##### Technology Stack & Integration Points
- Backend Technologies: FastAPI, LangChain, Vertex AI, BigQuery, ScaNN, PySpark.
- Frontend Technologies: React, Next.js, Tailwind CSS, Axios.
- Infrastructure Tools: Terraform, Docker.
- Cloud Provider: Google Cloud Platform services (BigQuery, Vertex AI, Cloud Storage, Cloud Run).
- Dependencies (such as the integration between Vertex AI and LangChain for RAG).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Processing Pipeline
    subgraph "Data Processing Pipeline"
        ETL["Data Ingestion & ETL (etl_full.py)"]:::datapipe
        SQL1["Table Creator (bigQuery/table creator.sql)"]:::datapipe
        SQL2["Vector Index (bigQuery/vector_index.sql)"]:::datapipe
        SQL3["Embedded Generation (bigQuery/embedded generation_2.sql)"]:::datapipe
        SQL4["Search Result (bigQuery/search_result.sql)"]:::datapipe
        BQ["BigQuery Database"]:::datapipe
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        FastAPI["FastAPI API Service (backend/app/main.py)"]:::backend
        SearchEP["Search Endpoint (backend/app/api/search_endpoints.py)"]:::backend
        SentimentEP["Sentiment Endpoint (backend/app/api/sentiment_endpoints.py)"]:::backend
        RAG["RAG Pipeline (backend/app/core/rag_pipeline.py)"]:::backend
        SearchEngine["Search Engine (backend/app/core/search_engine.py)"]:::backend
        SearchService["Search Service (backend/app/core/search_service.py)"]:::backend
        BQRetriever["BigQuery Retriever (backend/app/core/bigquery_retriever.py)"]:::backend
        BQClient["BigQuery Client (backend/app/db/bigquery_client.py)"]:::backend
        VertexAdapter["Vertex AI Adapter (backend/app/llm/vertex_adapter.py)"]:::backend
        VertexUtils["Vertex AI Utils (backend/app/llm/vertex_ai_utils.py)"]:::backend
        ConfigUtils["Config & Utilities (backend/app/config.py, backend/app/dependencies.py, backend/app/utils/helpers.py)"]:::backend
    end

    %% Frontend Web Interface
    subgraph "Frontend Web Interface"
        Layout["Layout (frontend/app/layout.tsx)"]:::frontend
        Page["Page (frontend/app/page.tsx)"]:::frontend
        Globals["Globals CSS (frontend/app/globals.css)"]:::frontend
        Chatbot["Chatbot Interface (frontend/components/ChatbotInterface.tsx)"]:::frontend
        FullChat["Full Page Chat (frontend/components/FullPageChat.tsx)"]:::frontend
        MaximizedChat["Maximized Chatbox (frontend/components/MaximizedChatbox.tsx)"]:::frontend
        ProductCard["Product Card (frontend/components/ProductCard.tsx)"]:::frontend
        ProductGrid["Product Grid (frontend/components/ProductGrid.tsx)"]:::frontend
        ThemeProvider["Theme Provider (frontend/components/theme-provider.tsx)"]:::frontend
        APIUtils["API Utilities (frontend/utils/api.ts)"]:::frontend
        DescParser["Description Parser (frontend/utils/descriptionParser.ts)"]:::frontend
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        Terraform["Terraform Configurations (infra/cloud_sql.tf, infra/embeddings.tf, infra/iam.tf, infra/secrets.tf, infra/variables.tf, infra/versions.tf, infra/embeddings_gcp.py)"]:::infra
        InfraDocker["Infra Dockerfile (infra/Dockerfile)"]:::infra
        BackendDocker["Backend Dockerfile (backend/Dockerfile)"]:::infra
        CICD["CI/CD Pipeline ( .github/workflows/publish.yml )"]:::infra
    end

    %% Connections from Data Processing to BigQuery
    ETL --> BQ
    SQL1 --> BQ
    SQL2 --> BQ
    SQL3 --> BQ
    SQL4 --> BQ

    %% Connections in Backend API Layer
    BQ --> BQClient
    FastAPI -->|"calls"| SearchEP
    FastAPI -->|"calls"| SentimentEP
    SearchEP -->|"utilizes"| RAG
    SentimentEP -->|"utilizes"| RAG
    RAG -->|"invokes"| SearchEngine
    RAG -->|"invokes"| SearchService
    RAG -->|"fetches"| BQRetriever
    BQRetriever --> BQClient
    RAG -->|"integrates"| VertexAdapter
    RAG -->|"integrates"| VertexUtils
    FastAPI -->|"configured_by"| ConfigUtils

    %% Frontend Interaction with Backend
    Layout -->|"API-call"| FastAPI
    Chatbot -->|"sends message to"| FastAPI

    %% Infrastructure provisioning connections
    Terraform --- BQ
    Terraform --- VertexAdapter
    Terraform --- FastAPI
    CICD --> InfraDocker
    CICD --> BackendDocker

    %% Styling classes
    classDef datapipe fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;
    classDef backend fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef frontend fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef infra fill:#FFE0B2,stroke:#E65100,stroke-width:2px;

    %% Click Events for Data Processing Pipeline
    click ETL "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/etl_full.py"
    click SQL1 "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/bigQuery/table creator.sql"
    click SQL2 "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/bigQuery/vector_index.sql"
    click SQL3 "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/bigQuery/embedded generation_2.sql"
    click SQL4 "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/bigQuery/search_result.sql"

    %% Click Events for Backend API Layer
    click FastAPI "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/main.py"
    click SearchEP "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/api/search_endpoints.py"
    click SentimentEP "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/api/sentiment_endpoints.py"
    click RAG "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/core/rag_pipeline.py"
    click SearchEngine "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/core/search_engine.py"
    click SearchService "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/core/search_service.py"
    click BQRetriever "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/core/bigquery_retriever.py"
    click BQClient "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/db/bigquery_client.py"
    click VertexAdapter "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/llm/vertex_adapter.py"
    click VertexUtils "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/llm/vertex_ai_utils.py"
    click ConfigUtils "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/backend/app/config.py"

    %% Click Events for Frontend Web Interface
    click Layout "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/app/layout.tsx"
    click Page "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/app/page.tsx"
    click Globals "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/app/globals.css"
    click Chatbot "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/components/ChatbotInterface.tsx"
    click FullChat "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/components/FullPageChat.tsx"
    click MaximizedChat "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/components/MaximizedChatbox.tsx"
    click ProductCard "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/components/ProductCard.tsx"
    click ProductGrid "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/components/ProductGrid.tsx"
    click ThemeProvider "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/components/theme-provider.tsx"
    click APIUtils "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/utils/api.ts"
    click DescParser "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/frontend/utils/descriptionParser.ts"

    %% Click Events for Infrastructure & Deployment
    click Terraform "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/infra/cloud_sql.tf"
    click InfraDocker "https://github.com/polarbear333/rag-llm-based-recommender/tree/main/infra/Dockerfile"
    click BackendDocker "https://github.com/polarbear333/rag-llm-based-recommender/tree/main/backend/Dockerfile"
    click CICD "https://github.com/polarbear333/rag-llm-based-recommender/blob/main/.github/workflows/publish.yml"
```
