# aianytime/agentic-rag-using-langgraph architecture

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

- Interactive diagram: https://gitdiagram.com/aianytime/agentic-rag-using-langgraph
- Repository: https://github.com/aianytime/agentic-rag-using-langgraph

## Overview

##### Project Type & Purpose
- This is a backend service—a conversational Retrieval-Augmented Generation (RAG) pipeline.
- Purpose: Accept multi-turn user queries, preserve context, filter off-topic requests, retrieve and evaluate documents from a vector store, refine failed searches, and generate grounded responses via an LLM.

##### File Structure Analysis
- Top-level files:
- langgraph_rag_system.py – contains the entire workflow definition (graph nodes, edges, LLM & vector store setup, state model).
- pyproject.toml, uv.lock – project metadata and dependency lock for the UV build tool.
- README.md – detailed architecture and usage guide.
- No separate frontend or microservices—everything lives in one Python process orchestrated by LangGraph.

##### Key README Insights
- The “System Architecture” section spells out a node-based flow chart (rephrase → classify → fetch → evaluate → tweak/retry → respond/fallback).
- External services: OpenAI API for embeddings & chat, Chroma vector DB for retrieval, LangGraph for workflow orchestration.

##### Main Components
a. Ingress: User (via CLI or API)
b. Workflow Engine: LangGraph StateGraph
c. State Store / Memory: MemorySaver or SqliteSaver checkpoint
d. Vector Database: Chroma or other vectorstore
e. LLM Service: OpenAI ChatOpenAI & OpenAIEmbeddings
f. Document Management: Document loader component
g. Control Logic Nodes:
‑ Rephrase Query
‑ Classify Topic
‑ Fetch Documents
‑ Evaluate Documents
‑ Tweak Question (Retry)
‑ Create Response / Fallback

##### Relationships & Data Flow
1. User question → StateGraph entry node (“Rephrase Query”)
2. “Rephrase Query” → “Classify Topic”
3. “Classify Topic” → if off-topic: “Reject Off-Topic” → END
else → “Fetch Documents”
4. “Fetch Documents” → Vector DB (Chroma) → returns docs → “Evaluate Documents”
5. “Evaluate Documents” → if relevant docs found: “Create Response” → END
else if attempts < max: “Tweak Question” → back to “Fetch Documents”
else → “Fallback Response” → END
- Each node may invoke the LLM service for structured output or generation.

##### Architectural Patterns & Principles
- Graph-based workflow (StateGraph) for modular, reusable nodes
- Stateful design: DialogState TypedDict holds conversation history, retrieved_docs, query refinements, flags
- Retry logic & self-correction: conditional branching based on evaluation results
- Clear separation of concerns: query rewriting, classification, retrieval, evaluation, response generation

##### Technology Stack Labels
- Python 3.11 runtime
- UV (uv) build & execution tool
- LangGraph (StateGraph, nodes, edges)
- LangChain Core / langchain_openai / langchain_community
- Chroma vector database
- OpenAI API (ChatOpenAI, OpenAIEmbeddings)
- pydantic for structured outputs
- dotenv for configuration

##### Final Advice
- Be exhaustive: even though the code is in one file, break it into logical components.
- Iterative retry loop explicitly.
- How state flows from node to node via the TypedDict.
- Keep labels concise but precise—derive them from function names and state keys.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Query Preprocessing
    subgraph "Query Preprocessing"
        Start(("User (CLI/API)")):::startend
        Rephrase["rephrase_query()"]:::process
        Classify{"classify_topic()"}:::decision
    end

    %% Retrieval Workflow
    subgraph "Retrieval Workflow"
        Fetch["fetch_documents()"]:::process
        VectorDB[(Chroma vectorstore)]:::data
        Evaluate{"evaluate_documents()"}:::decision
        Tweak["tweak_question()"]:::process
    end

    %% Response Generation
    subgraph "Response Generation"
        Create["create_response()"]:::process
        Fallback["fallback_response()"]:::process
    end

    %% Off-topic Rejection
    Reject["reject_off_topic()"]:::process

    %% External and Data Stores
    Memory[(MemorySaver/SqliteSaver)]:::data
    LLM[(OpenAI API)]:::external
    DocLoader["document_loader"]:::process

    %% Project Files
    subgraph "Project Files"
        P1["pyproject.toml"]:::file
        P2["uv.lock"]:::file
        P3["README.md"]:::file
        P4["LICENSE"]:::file
        P5[".python-version"]:::file
        P6[".gitignore"]:::file
    end

    %% Data Flows
    Start --> Rephrase
    Rephrase --> Classify
    Classify -->|Off-topic| Reject
    Classify -->|On-topic| Fetch
    Fetch --> VectorDB
    VectorDB --> Fetch
    Fetch --> DocLoader
    DocLoader --> Fetch
    Fetch --> Evaluate
    Evaluate -->|Relevant| Create
    Evaluate -->|NotRelevant & attempts<max| Tweak
    Evaluate -->|NotRelevant & attempts>=max| Fallback
    Tweak --> Fetch
    Create --> End[("End")]:::startend
    Fallback --> End
    Reject --> End

    %% LLM Invocations
    Rephrase -->|calls LLM| LLM
    Classify -->|calls LLM| LLM
    Evaluate -->|calls LLM| LLM
    Create -->|calls LLM| LLM

    %% State Store Access
    Memory -.-> Rephrase
    Memory -.-> Fetch
    Create -.-> Memory

    %% Click Events
    click Start "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Rephrase "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Classify "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Reject "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Fetch "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Evaluate "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Tweak "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Create "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Fallback "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click Memory "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click VectorDB "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click LLM "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click DocLoader "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/langgraph_rag_system.py"
    click P1 "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/pyproject.toml"
    click P2 "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/uv.lock"
    click P3 "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/README.md"
    click P4 "https://github.com/aianytime/agentic-rag-using-langgraph/tree/main/LICENSE"
    click P5 "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/.python-version"
    click P6 "https://github.com/aianytime/agentic-rag-using-langgraph/blob/main/.gitignore"

    %% Styles
    classDef startend fill:#f9f,stroke:#333,stroke-width:1px
    classDef process fill:#bbf,stroke:#333,stroke-width:1px
    classDef decision fill:#ffd,stroke:#333,stroke-width:1px
    classDef data fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#fbf,stroke:#333,stroke-width:1px
    classDef file fill:#eee,stroke:#999,stroke-dasharray:2,stroke-width:1px
```
