# chintamanil/review-genie architecture

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

- Interactive diagram: https://gitdiagram.com/chintamanil/review-genie
- Repository: https://github.com/chintamanil/review-genie

## Overview

##### Project type and purpose
- A monolithic Python application implementing a Retrieval-Augmented Generation (RAG) evaluation pipeline for Amazon-product queries.
- Purpose: retrieve relevant docs via FAISS, generate answers with an LLM, evaluate those answers across four metrics, and log everything to LangSmith.

##### File structure
- app.py: the single orchestrator (retrieval → generation → evaluation → logging).
- faiss_index/: pre-built FAISS vector store files (index.faiss, index.pkl).
- prod_small.csv: evaluation dataset (questions + ground truths).
- README.md: documentation and setup instructions.

##### README for architecture hints
- Uses LangChain for pipeline construction.
- OpenAI embeddings for retrieval, OpenAI chat for generation and evaluation.
- FAISS for nearest-neighbor search over product docs.
- LangSmith for tracing and experiment management.
- Four separate evaluators (correctness, relevance, groundedness, retrieval relevance).

##### Main components & interactions
a. Data Layer
- Evaluation Dataset (prod_small.csv)
- FAISS Vector Store (faiss_index/)
b. Retrieval Module
- OpenAI Embedding API → query embeddings
- FAISS index lookup → retrieved docs
c. Generation Module
- OpenAI Chat API → generates answer from retrieved docs
d. Evaluation Module
- Four LLM-based evaluators (each calls OpenAI to judge one metric)
e. Orchestration & Tracing
- app.py ties all steps
- LangSmith SDK logs traces & results

##### Data flow & relationships
User Query → Orchestrator (app.py)
→ Embedding Service (OpenAI Embeddings)
→ FAISS Index lookup
→ Retrieved Documents → LLM Generation (OpenAI Chat)
→ Generated Answer → Evaluation Module (4 evaluator calls)
→ Results & traces → LangSmith Dashboard

##### Architectural patterns & design principles
- Pipeline pattern: sequential stages (retrieve → generate → evaluate).
- Single Responsibility: each evaluator addresses one quality metric.
- Externalized state: FAISS index on disk; LangSmith stores experiment metadata.
- Clear separation of concerns across modules inside one script.

##### Key technologies
- Python 3.8+
- LangChain (pipeline helpers)
- FAISS (vector search)
- OpenAI API (embeddings + chat)
- LangSmith SDK (observability & experiment tracking)

##### Essential details not to omit
- The FAISS index files as the core retrieval mechanism.
- The four distinct evaluators and their LLM calls.
- Environment variables (API keys, tracing flags) near the orchestrator.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        dataset["Evaluation Dataset\n(prod_small.csv)"]:::datastore
        faiss_index["FAISS Vector Store\n(faiss_index/)"]:::datastore
    end

    %% Orchestrator
    orchestrator["Orchestrator\n(app.py)\n(Environment Variables)"]:::orchestrator

    %% Retrieval Stage
    subgraph "Retrieval Stage"
        embed["OpenAI Embeddings"]:::external
    end

    %% Generation Stage
    subgraph "Generation Stage"
        gen["LLM Generation\n(OpenAI Chat)"]:::external
    end

    %% Evaluation Stage
    subgraph "Evaluation Stage"
        eval1["Correctness Evaluator"]:::module
        eval2["Relevance Evaluator"]:::module
        eval3["Groundedness Evaluator"]:::module
        eval4["Retrieval Relevance Evaluator"]:::module
    end

    %% External Services
    langsmith["LangSmith"]:::external

    %% Documentation
    doc["README.md"]:::doc

    %% Data Flow
    dataset -->|loads questions| orchestrator
    orchestrator -->|"generate embeddings"| embed
    embed -->|"retrieve docs"| faiss_index
    faiss_index -->|"return documents"| orchestrator

    orchestrator -->|"generate answer"| gen
    gen -->|"return answer"| orchestrator

    orchestrator -->|"evaluate correctness"| eval1
    orchestrator -->|"evaluate relevance"| eval2
    orchestrator -->|"evaluate groundedness"| eval3
    orchestrator -->|"evaluate retrieval relevance"| eval4

    eval1 -->|"score"| orchestrator
    eval2 -->|"score"| orchestrator
    eval3 -->|"score"| orchestrator
    eval4 -->|"score"| orchestrator

    orchestrator -->|"log traces & metrics"| langsmith

    orchestrator -->|"see docs"| doc

    %% Click Events
    click orchestrator "https://github.com/chintamanil/review-genie/blob/main/app.py"
    click dataset "https://github.com/chintamanil/review-genie/blob/main/prod_small.csv"
    click faiss_index "https://github.com/chintamanil/review-genie/tree/main/faiss_index/"
    click doc "https://github.com/chintamanil/review-genie/blob/main/README.md"

    %% Styles
    classDef datastore fill:#D1E8FF,stroke:#0366D6,stroke-width:1px
    classDef external fill:#FFE6CC,stroke:#D9721F,stroke-width:1px
    classDef module fill:#E6FFCC,stroke:#2E8B57,stroke-width:1px
    classDef orchestrator fill:#E8D1FF,stroke:#6A0DAD,stroke-width:2px
    classDef doc fill:#F2F2F2,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2
```
