flowchart TD
    subgraph DEPLOY["🚢 Deployment Layer"]
        FE["🌐 Frontend Client"] --> LB["⚖️ Nginx LB :8080"]
        CFG["docker-compose.nginx.yml + .env"] --> API1["🐳 rag-api-1"]
        CFG --> API2["🐳 rag-api-2"]
        CFG --> API3["🐳 rag-api-3"]
        API1 --> LB
        API2 --> LB
        API3 --> LB
        HC["Healthchecks gate traffic"] --> LB
        LB --> CHAT["POST /api/chat\nPOST /api/chat/stream"]
        LB --> OPS["GET /api/health /ready /load /limits"]
        ERR["502/429/503"] --> RETRY["Client retry + backoff"]
    end

    subgraph API["🧩 FastAPI Runtime Layer"]
        CHAT --> SS["In-memory Session Store"]
        CHAT --> RL["Local Rate + Load Guardrails"]
        CHAT --> KP["Busy-key Failover Pool"]
        CHAT --> LOG["JSONL Chat Logger"]
        SS --> R
        RL --> R
        KP --> R
        LOG --> EV["logs/events.jsonl"]
        LOG --> IPL["logs/<client_ip>.jsonl"]
        LOG --> ROT["Rotating files\n5MB x 7 backups"]
        OPS --> OBS["Metrics + status endpoints"]
        OBS --> ERR
    end

    subgraph INGESTION["🕷️ Data Ingestion Layer"]
        A["🌐 sahrdaya.ac.in"] -->|"sitemap<br/>discovery"| B["🗺️ URL Queue"]
        B -->|"4 threads"| C["🎭 Playwright<br/>Renderer"]
        C -->|"open modals<br/>click Stats/Download"| C2["📎 Popup Link<br/>Capture"]
        C2 -->|"inject discovered<br/>PDF URLs"| D["🧹 BS4<br/>Cleaner"]
        C -->|"JS execution<br/>+ DOM parse"| D
        D --> E["📄 data/raw/sahrdaya_rag.txt<br/>~2K chunks"]
    end

    subgraph ETL["⚙️ ETL Pipeline"]
        E -->|"NLTK sentence<br/>tokenizer"| F["✂️ Sentence<br/>Splitter"]
        F -->|"regex +<br/>pattern match"| G["🏷️ Category<br/>Tagger"]
        G -->|"alias<br/>injection"| H["📦 data/processed/data_cleaned.jsonl<br/>18 categories"]
        STTXT["📝 data/raw/student_inputs/*.txt"] --> STTXTLOAD["🧩 TXT Block Loader<br/>preprocess_data.py"]
        STTXTLOAD -->|"blank-line split<br/>+ chunk merge"| H
        E -->|"role-label<br/>parsing"| FP["👥 Former People<br/>Structurer"]
        FP -->|"10 role chunks<br/>+ summary"| H
        E -->|"legacy + listing<br/>parsing"| I["👤 Faculty<br/>Extractor"]
        E -->|"former people<br/>parsing"| IP["👥 Former People<br/>Parser"]
        STCSV["🧾 data/students.csv"] --> STING["👩‍🎓 student_db.py<br/>Normalizer + Loader"]
        I -->|"~109 profiles<br/>16 columns"| K["🗃️ SQLite DB<br/>data/sql/college.db"]
        IP -->|"52 records<br/>10 roles"| K
        STING -->|"students + interests + links<br/>projects + socials"| K
    end

    subgraph INDEX["📊 Multi-Index Layer"]
        H -->|"TF-IDF<br/>tokenization"| L["🔍 BM25<br/>Retriever"]
        H -->|"all-MiniLM-L6-v2<br/>384-dim"| M["🧠 FAISS<br/>Vector Store"]
        H -->|"chunk/category nodes"| G1["🕸️ Content Graph<br/>NetworkX"]
        TJSON["🗂️ data/raw/sahrdaya_tracking.json"] -->|"page/url/chunk links"| G1

        L -.->|"pickle"| N[("💾 .index_cache/")]
        M -.->|"save_local()"| N
        G1 -.->|"node-link JSON"| N
        N -.->|"data hash"| O{{"♻️ Cache<br/>Hit?"}}
        O -->|"yes"| P["⚡ Fast Load<br/>~0.1s"]
        O -->|"no"| Q["🔨 Rebuild<br/>indexes + graph"]
    end

    subgraph RUNTIME["❓ Query Runtime"]
        R(["🧑 User<br/>Query"]) --> QC["✍️ LLM Query<br/>Typo Corrector"]
        QC --> QM["🧭 Canonical Query Mapper<br/>deterministic + LLM"]
        QM --> QX["🔎 Query Expander<br/>dept + intent terms"]
        QX --> S["📝 Chat<br/>History"]
        QX --> SF["👤 Student Name<br/>Fast Path"]
        SF -->|"match"| V
        SF -->|"no match"| T
        S --> T{"🧠 LLM<br/>Classifier"}

        subgraph SQL["📊 SQL Path"]
            T -->|"bulk / aggregate /<br/>faculty + former + students"| U["🔧 Schema-Aware<br/>SQL Generator"]
            K --> U
            U -->|"SELECT only<br/>safety filter"| V["⚡ SQLite<br/>Executor"]
            V --> W["📋 Formatted SQL<br/>Result"]
            V -->|"error"| X["🔄 Fallback<br/>to RAG"]
        end

        subgraph RAG["📚 Retrieval Path (GraphRAG + Hybrid)"]
            T -->|"single-person /<br/>general"| GH{"🧭 Graph Intent<br/>Heuristic?"}
            X --> GH

            GH -->|"yes"| GR["🕸️ GraphRAG<br/>Retriever"]
            G1 --> GR
            GR --> GE{"strong<br/>graph evidence?"}
            GE -->|"yes"| AD["💬 Groq LLM<br/>Generation"]

            GH -->|"no"| Y["🔎 Hybrid Retriever"]
            GE -->|"no"| Y
            Y --> Z["⚡ Ensemble<br/>Retriever"]
            L -->|"weight: 0.6"| Z
            M -->|"weight: 0.4"| Z
            Z -->|"RRF<br/>fusion"| AA["📊 Top-25<br/>Candidates"]
            AA --> AB["🤖 Cross-Encoder<br/>ms-marco-MiniLM"]
            AB -->|"rerank"| AC["🎯 Top-10<br/>Relevant"]
            AC --> AD
        end
    end

    subgraph OUTPUT["✅ Output Layer"]
        W --> AE(["📨 Response"])
        AD --> AE
        AE --> AF["📊 Token<br/>Counter"]
        AE --> AG["🔢 Chunk<br/>Tracker"]
        AF & AG --> AH["📈 Session<br/>Analytics"]
        AH --> AI["📉 /graph<br/>Dashboard"]
        AH --> AJ["📋 /stats<br/>Summary"]
    end

    style INGESTION fill:none,stroke:#4a9eff,stroke-width:2px
    style ETL fill:none,stroke:#22c55e,stroke-width:2px
    style INDEX fill:none,stroke:#a855f7,stroke-width:2px
    style RUNTIME fill:none,stroke:#f97316,stroke-width:2px
    style API fill:none,stroke:#ff7f50,stroke-width:2px
    style DEPLOY fill:none,stroke:#7b61ff,stroke-width:2px
    style SQL fill:none,stroke:#ef4444,stroke-width:1px,stroke-dasharray: 5 5
    style RAG fill:none,stroke:#06b6d4,stroke-width:1px,stroke-dasharray: 5 5
    style G1 fill:none,stroke:#0ea5e9,stroke-width:1px,stroke-dasharray: 4 4
    style GR fill:none,stroke:#0ea5e9,stroke-width:1px,stroke-dasharray: 4 4
    style OUTPUT fill:none,stroke:#eab308,stroke-width:2px

flowchart TD
    U[User Query] --> N[Normalize + Canonicalize]
    N --> S{Single-student fast match?}
    S -->|yes| SQ[Direct Student SQL]
    S -->|no| B{Bulk SQL intent?}
    B -->|yes| SG[Generate SQL]
    SG --> SX{SQL success with rows?}
    SX -->|yes| A[Answer mode: sql]
    SX -->|no| G
    B -->|no| G{Graph intent heuristic?}
    G -->|yes| GR[GraphRAG content graph retrieval]
    GR --> GE{Strong graph evidence?}
    GE -->|yes| L[Groq generation]
    GE -->|no| H
    G -->|no| H[Hybrid BM25 + FAISS + reranker]
    H --> L
    SQ --> A
    L --> AR[Answer mode: graph_rag or rag]

flowchart LR
     A[Code changes] --> B[Build API image from Dockerfile]
     B --> C[Start rag-api-1, rag-api-2, rag-api-3]
     C --> D[Health checks on /api/health]
     D --> E{All healthy?}
     E -->|Yes| F[Start Nginx reverse proxy]
     E -->|No| G[Keep service out of traffic]
     F --> H[Serve traffic on :8080]