# jayjajoo/corrective_rag architecture

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

- Interactive diagram: https://gitdiagram.com/jayjajoo/corrective_rag
- Repository: https://github.com/jayjajoo/corrective_rag

## Overview

##### Project Type and Purpose
- This is an open-source, full-stack Python application implementing a corrective Retrieval-Augmented Generation (RAG) QA system.
- It combines a Streamlit UI (`app.py`) with a modular backend agent pipeline (`agent.py`, `rag.py`), integrates a vector database (ChromaDB), LLMs (OpenAI GPT-4.1), and an external web search API (Tavily).
- Its goal is to dynamically decide between vector retrieval and web search, grade document relevance, and generate accurate answers with cost-efficient LLM calls.

##### File Structure Analysis
- Top-level scripts:
- `app.py` – Streamlit frontend for file upload, UI toggles (web search on/off), and chat interface.
- `agent.py` – Orchestration layer that ties together intent detection, routing logic, and invokes the RAG pipeline.
- `rag.py` – Core RAG implementation: vector DB queries, web search calls, quality grading, and response generation.
- Configuration:
- `requirements.txt` – Python dependencies (LangChain, LangGraph, ChromaDB, Streamlit, OpenAI SDK, Tavily).
- `.gitignore` – standard exclusions.
- No separate folder structure indicates a monolithic deployment, but clear logical separation by module.

##### Key Architecture Insights from README
- Workflow stages (state graph):
1. capture_intent
2. initial_route → decides between web search vs. vector RAG
3. rephrase_query (context-aware)
4. rag_or_web_router → to vector retriever or web search
5. quality_grader → if below threshold, re-route to web_search
6. summarize (LLM answer generation)
- External integrations:
- ChromaDB vector store for embeddings & retrieval
- Tavily Search API for live web lookup
- OpenAI GPT-4.1 for classification, grading, summarization
- LangGraph’s StateGraph for stateful workflow management
- Streamlit for UI and document processors (PDF, DOCX, TXT, CSV)

##### Main Components and Their Relationships
- Frontend (Streamlit UI)
- Upload documents → Document Processor → build vector store
- Chat interface sends user messages to agent
- Agent/Orchestration Layer
- Intent Detector → Query Rephraser → Retrieval Router
- Quality Grader → Final Router to summarizer
- MemorySaver for chat history (LangGraph state)
- Retrieval Services
- Vector DB (ChromaDB) ↔ embeddings & similarity search
- Web Search (Tavily API) for out-of-vector-scope queries
- LLM Services
- OpenAI endpoints for intent detection, relevancy grading, and text generation
- Data Stores
- Local/in-memory document store (built at runtime)
- ChromaDB persistent vector store

##### Architectural Patterns and Design Principles
- Modular layering: UI ↔ Orchestrator ↔ Retrieval & LLM services
- State machine pattern via LangGraph’s StateGraph
- Separation of concerns: `agent.py` (control flow) vs. `rag.py` (RAG logic) vs. `app.py` (presentation)
- Dynamic routing for cost-accuracy trade-off (vector vs. web search)
- Extensibility points: plug new document types or search APIs, adjust quality threshold

##### Essential Details to Capture
- StateGraph sequence with labels on transitions (e.g., “is_asking_for_web_search → rephrase_query”)
- Quality threshold logic branch
- Toggle for web search in UI and its effect on routing
- Multi-document processing before vector store build

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        App["Streamlit App"]:::ui
        DocProc["Document Processor"]:::ui
    end

    App -->|"upload docs"| DocProc
    App -->|"user message"| Intent

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Intent["capture_intent"]:::orchestrator
        Rephrase["rephrase_query"]:::orchestrator
        InitialRoute["initial_route"]:::orchestrator
        Router["rag_or_web_router"]:::orchestrator
        Grade["quality_grader"]:::orchestrator
        Summarizer["summarize"]:::orchestrator
    end

    Intent -->|"intent detected"| Rephrase
    Rephrase --> InitialRoute
    InitialRoute --> Router

    %% Service Layer
    subgraph "Service Layer"
        OAAPI["OpenAI GPT-4.1 API"]:::service
        ChromaAPI["ChromaDB"]:::service
        TavilyAPI["Tavily Search API"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        VecStore["ChromaDB Vector Store"]:::data
        MemStore["Conversation Memory"]:::data
    end

    %% Routing to services
    Router -->|"vector path"| ChromaAPI
    Router -->|"web path"| TavilyAPI

    %% Service interactions
    Intent -->|"OpenAI API"| OAAPI
    Rephrase -->|"OpenAI API"| OAAPI
    Grade -->|"OpenAI API"| OAAPI
    Summarizer -->|"OpenAI API"| OAAPI

    ChromaAPI --> Grade
    TavilyAPI --> Grade

    Grade -->|"high"| Summarizer
    Grade -->|"low"| TavilyAPI

    Summarizer --> App
    DocProc --> VecStore
    Summarizer -.-> MemStore

    %% File References
    subgraph "Project Files"
        Req["requirements.txt"]:::file
        Readme["README.md"]:::file
        Gitignore[".gitignore"]:::file
    end

    %% Click Events
    click App "https://github.com/jayjajoo/corrective_rag/blob/main/app.py"
    click DocProc "https://github.com/jayjajoo/corrective_rag/blob/main/app.py"
    click Intent "https://github.com/jayjajoo/corrective_rag/blob/main/agent.py"
    click Rephrase "https://github.com/jayjajoo/corrective_rag/blob/main/agent.py"
    click InitialRoute "https://github.com/jayjajoo/corrective_rag/blob/main/agent.py"
    click Router "https://github.com/jayjajoo/corrective_rag/blob/main/agent.py"
    click Grade "https://github.com/jayjajoo/corrective_rag/blob/main/rag.py"
    click Summarizer "https://github.com/jayjajoo/corrective_rag/blob/main/rag.py"
    click Req "https://github.com/jayjajoo/corrective_rag/blob/main/requirements.txt"
    click Readme "https://github.com/jayjajoo/corrective_rag/blob/main/README.md"
    click Gitignore "https://github.com/jayjajoo/corrective_rag/blob/main/.gitignore"

    %% Styles
    classDef ui fill:#dae8fc,stroke:#6c8ebf,color:#073763,stroke-width:1px;
    classDef orchestrator fill:#d5e8d4,stroke:#82b366,color:#275a30,stroke-width:1px;
    classDef service fill:#ffe6cc,stroke:#d79b00,color:#663c00,stroke-width:1px;
    classDef data fill:#f2f2f2,stroke:#999999,color:#333333,stroke-width:1px;
    classDef file fill:#ffffff,stroke:#999999,color:#333333,stroke-width:1px,stroke-dasharray: 2 2;
    class App,DocProc ui
    class Intent,Rephrase,InitialRoute,Router,Grade,Summarizer orchestrator
    class OAAPI,ChromaAPI,TavilyAPI service
    class VecStore,MemStore data
    class Req,Readme,Gitignore file
```
