# mustafa-shoukat1/ragcraft-by-mustafa-shoukat architecture

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

- Interactive diagram: https://gitdiagram.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat
- Repository: https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat

## Overview

##### Project type and purpose
- This is a monolithic “monorepo” hosting a curated collection of Retrieval-Augmented Generation (RAG) tutorial apps and AI-agent demos.
- Its purpose is to showcase and provide runnable examples of LLM-based RAG applications using various models (OpenAI, Anthropic, Google Gemini, DeepSeek, Qwen, Llama, Cohere, etc.), vector stores, and retrieval strategies.

##### File structure
- Top-level:
- A root Readme.md describing the overall “Awesome LLM Apps” catalog.
- Multiple peer directories, each a self-contained RAG or agent project (agentic_rag, agentic_rag_math_agent, ai_blog_search, autonomous_rag, …, vision_rag).
- Within each project folder:
- A README.md explaining that specific app’s purpose, usage, and dependencies.
- A requirements.txt listing Python dependencies.
- One or more Python modules (e.g., main.py, app.py, <agent>.py) implementing the RAG pipeline or agent logic.
- Some have subdirectories for config (.env), data ingestion, benchmarking, logs, or specialized modules (vector.py, query_router.py, guardrails.py).
- There are no shared libraries at root—each app is effectively a standalone microservice.

##### README for additional insights
- The root README classifies projects into categories (AI Agents, Multi-agent Teams, Voice, MCP, RAG, etc.).
- The RAG section lists these tutorial apps and hints at common patterns: retrieving from vector store, routing queries, LLM calls, corrective loops, hybrid search.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level repo
    RepoCatalog["Repo Catalog"]:::catalog
    click RepoCatalog "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/Readme.md"

    %% RAG Tutorial Apps
    subgraph "RAG Tutorial Apps"
        direction TB
        AR["agentic_rag"]:::code
        click AR "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag/rag_agent.py"
        ARW["agentic_rag_with_reasoning"]:::code
        click ARW "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_with_reasoning/rag_reasoning_agent.py"
        AI["ai_blog_search"]:::code
        click AI "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/ai_blog_search/app.py"
        AU["autonomous_rag"]:::code
        click AU "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/autonomous_rag/autorag.py"
        CR["corrective_rag"]:::code
        click CR "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/corrective_rag/corrective_rag.py"
        DS["deepseek_local_rag_agent"]:::code
        click DS "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/deepseek_local_rag_agent/deepseek_rag_agent.py"
        GA["gemini_agentic_rag"]:::code
        click GA "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/gemini_agentic_rag/agentic_rag_gemini.py"
        HS["hybrid_search_rag"]:::code
        click HS "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/hybrid_search_rag/main.py"
        LL["llama3.1_local_rag"]:::code
        click LL "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/llama3.1_local_rag/llama3.1_local_rag.py"
        LH["local_hybrid_search_rag"]:::code
        click LH "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/local_hybrid_search_rag/local_main.py"
        LR["local_rag_agent"]:::code
        click LR "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/local_rag_agent/local_rag_agent.py"
        QL["qwen_local_rag"]:::code
        click QL "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/qwen_local_rag/qwen_local_rag_agent.py"
        RS["rag-as-a-service"]:::code
        click RS "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/rag-as-a-service/rag_app.py"
        RC["rag_chain"]:::code
        click RC "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/rag_chain/app.py"
        RD["rag_database_routing"]:::code
        click RD "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/rag_database_routing/rag_database_routing.py"
        VR["vision_rag"]:::code
        click VR "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/vision_rag/vision_rag.py"
    end

    %% Detailed example: agentic_rag_math_agent
    subgraph "agentic_rag_math_agent" 
        direction TB
        M_UI["Streamlit UI"]:::ui
        click M_UI "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/app/streamlit.py"
        M_Bench["Benchmark Results"]:::data
        click M_Bench "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/benchmark/results_math_5.csv"
        click M_Bench "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/benchmark/results_math_50.csv"
        M_BenchScript["Benchmark Script"]:::code
        click M_BenchScript "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/app/benchmark.py"
        M_Config["Config/Secrets (.env)"]:::config
        click M_Config "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/config/.env"
        M_Data["Data Ingestion"]:::code
        click M_Data "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/data/load_gsm8k_data.py"
        M_Router["Query Router"]:::code
        click M_Router "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/rag/query_router.py"
        M_Vector["Vector Logic"]:::code
        click M_Vector "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/rag/vector.py"
        M_Guard["Guardrails"]:::code
        click M_Guard "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/rag/guardrails.py"
        M_Log["Feedback Log"]:::logs
        click M_Log "https://github.com/mustafa-shoukat1/ragcraft-by-mustafa-shoukat/blob/main/agentic_rag_math_agent/logs/feedback_log.json"
    end

    %% Pipeline flow for math agent
    M_UI -->|requests| M_Config
    M_Config --> M_Data
    M_Data --> M_Router
    M_Router --> M_Vector
    M_Vector -->|index query| VectorStore
    M_Vector --> LLM
    LLM --> M_Guard
    M_Guard --> M_Log

    %% External and infrastructure
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI"]:::ext
        Anthropic["Anthropic"]:::ext
        Gemini["Google Gemini"]:::ext
        Cohere["Cohere"]:::ext
        DeepSeek["DeepSeek"]:::ext
        Llama3["Llama3 Local"]:::ext
        Qwen["Qwen Local"]:::ext
    end

    subgraph "Vector Stores & Data"
        direction TB
        VectorStore["Vector Store"]:::store
        DataCSV["Local CSV/GSM8K"]:::store
    end

    %% Connections to external
    VectorStore --> DataCSV
    M_Vector --> VectorStore
    LLM --> OpenAI
    LLM --> Anthropic
    LLM --> Gemini
    LLM --> Cohere
    LLM --> DeepSeek
    LLM --> Llama3
    LLM --> Qwen

    %% User interface entry
    User["User"]:::user
    User --> M_UI

    %% Styles
    classDef catalog fill:#D0E1F9,stroke:#1B4F72,color:#1B4F72;
    classDef code fill:#AED6F1,stroke:#2E86C1,color:#1B2631;
    classDef ui fill:#FCF3CF,stroke:#D4AC0D,color:#6E2C00;
    classDef store fill:#A9DFBF,stroke:#196F3D,color:#1E8449;
    classDef ext fill:#F5CBA7,stroke:#BA4A00,color:#873600;
    classDef config fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef data fill:#A3E4D7,stroke:#148F77,color:#0E6251;
    classDef logs fill:#D5D8DC,stroke:#566573,color:#2E4053;
    classDef user fill:#FADBD8,stroke:#C0392B,color:#641E16;
```
