# lelekhoa1812/aitc-localbot architecture

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

- Interactive diagram: https://gitdiagram.com/lelekhoa1812/aitc-localbot
- Repository: https://github.com/lelekhoa1812/aitc-localbot

## Overview

##### Project type and purpose
- This is a full-stack, retrieval-augmented generation (RAG) system for answering compliance queries over hardware catalog PDFs.
- It ingests, parses, and indexes PDF text and images into a vector store + metadata store, then handles user queries via semantic search + LLM reasoning.

##### File structure
- Top-level:
– build/: Jupyter notebook for prototyping or offline processing
– cataloges/: raw PDF datasheets
– compliance/: sample outputs or test files
– middleware/: nginx config (nginx.txt) and a main.py (reverse-proxy or gateway logic)
– static/: web UI assets (index.html, script.js, styles.css)
– script/: helper scripts (resolver.py)
– system/: core backend (app.py, config/, control scripts, parser.py, embed.py, retrieval.py, grader.py, examiner.py, interpreter.py, memory.py, rotator.py, warmup.py, db.py) plus Dockerfile and requirements.txt
- Notable patterns: MVC-style separation (static UI / middleware / backend “system” code), a clear ingestion pipeline, persistent storage (MongoDB + FAISS), control scripts for deployment.

##### README insights
- Describes a seven-stage RAG pipeline:
1. PDF ingestion & parsing
2. Text chunking, embedding, vector indexing (FAISS) + metadata in MongoDB
3. Image processing (OCR + VLM captioning) fused into vector index
4. Query interpretation (parameter/operator/value extraction)
5. Semantic search against FAISS + metadata filtering
6. Compliance evaluation via Gemini Flash 2.0 (LLM reasoning, optional function-calling tools for numeric checks)
7. Structured response generation (matched value, compliance yes/no, source citation)
- Cold-start design: precompute and persist index + metadata to speed up query time.
- Technologies: Python, LangChain, FAISS, MongoDB, PyMuPDF/Unstructured, Tesseract, a VLM (e.g. BLIP-2 or LLaVA) for images, Gemini Flash API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client / UI Layer
    subgraph "Client / UI" 
        UIIndex["index.html"]:::ui
        UIScript["script.js"]:::ui
        UIStyles["styles.css"]:::ui
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        ProxyConfig["nginx.txt"]:::proxy
        ProxyLogic["main.py"]:::proxy
    end

    %% Backend Service / API
    subgraph "Backend Service (API)"
        App["app.py"]:::backend
        IndexMod["index.py"]:::backend
        Config["config.py"]:::backend
        Req["requirements.txt"]:::backend
        Dockerfile["Dockerfile"]:::backend
    end

    %% Cold-Start Ingestion Pipeline
    subgraph "Cold-Start Pipeline (Preprocessing)"
        Parser["PDF Parser"]:::backend
        Embed["Chunking & Embedding"]:::backend
        Warmup["Index Init / Warmup"]:::backend
        DBSetup["DB Setup (FAISS + MongoDB)"]:::backend
    end

    %% Query Pipeline (Runtime)
    subgraph "Query Pipeline"
        Interpreter["Query Interpreter"]:::backend
        QEmbed["Query Embedding"]:::backend
        Search["Semantic Search (FAISS)"]:::backend
        Metadata["Metadata Fetch (MongoDB)"]:::backend
        Grader["Compliance Grader"]:::backend
        Examiner["Response Generator"]:::backend
        Memory["Session Memory"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        FAISS["FAISS Vector Store"]:::datastore
        Mongo["MongoDB Metadata Store"]:::datastore
    end

    %% External Services & Resources
    subgraph "External"
        Gemini["Gemini Flash 2.0 API"]:::external
        RawPDF["Raw PDFs (cataloges/)"]:::external
    end

    %% Control & Helpers
    subgraph "Control & Helpers"
        Startup["startup.sh"]:::proxy
        Restart["restart.sh"]:::proxy
        Shutdown["shutdown.sh"]:::proxy
        Notebook["Offline Notebook"]:::backend
        Resolver["resolver.py"]:::backend
    end

    %% Connections: Client to Middleware
    UIIndex -->|requests| ProxyLogic
    UIScript -->|requests| ProxyLogic
    UIStyles -->|requests| ProxyLogic

    %% Middleware to Backend
    ProxyLogic -->|proxies API| App
    ProxyLogic -->|serves static| UIIndex

    %% Cold-Start Pipeline Flow
    Startup --> Parser
    Parser -->|"parse PDFs" | Embed
    Embed -->|"generate embeddings"| DBSetup
    DBSetup -->|"initialize index"| Warmup
    Warmup --> FAISS
    Warmup --> Mongo
    RawPDF --> Parser

    %% Query Pipeline Flow
    App --> Interpreter
    Interpreter --> QEmbed
    QEmbed --> Search
    Search -->|"top-k chunks"| Metadata
    Metadata --> Grader
    Grader -->|calls| Gemini
    Gemini --> Grader
    Grader --> Examiner
    Examiner --> Memory
    Examiner --> App
    App -->|responds| ProxyLogic

    %% Helper and Control
    Restart --> Startup
    Shutdown --> Restart
    Notebook --> Parser
    Resolver --> Parser

    %% Styling
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef proxy fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef backend fill:#98FB98,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px

    %% Click Events
    click UIIndex "https://github.com/lelekhoa1812/aitc-localbot/blob/main/static/index.html"
    click UIScript "https://github.com/lelekhoa1812/aitc-localbot/blob/main/static/script.js"
    click UIStyles "https://github.com/lelekhoa1812/aitc-localbot/blob/main/static/styles.css"
    click ProxyConfig "https://github.com/lelekhoa1812/aitc-localbot/blob/main/middleware/config/nginx.txt"
    click ProxyLogic "https://github.com/lelekhoa1812/aitc-localbot/blob/main/middleware/main.py"
    click App "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/app.py"
    click IndexMod "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/index.py"
    click Config "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/config.py"
    click Req "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/requirements.txt"
    click Dockerfile "https://github.com/lelekhoa1812/aitc-localbot/tree/main/system/Dockerfile"
    click Parser "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/parser.py"
    click Embed "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/embed.py"
    click Warmup "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/warmup.py"
    click DBSetup "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/db.py"
    click Interpreter "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/interpreter.py"
    click QEmbed "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/embed.py"
    click Search "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/retrieval.py"
    click Metadata "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/db.py"
    click Grader "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/grader.py"
    click Examiner "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/examiner.py"
    click Memory "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/memory.py"
    click Startup "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/control/startup.sh"
    click Restart "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/control/restart.sh"
    click Shutdown "https://github.com/lelekhoa1812/aitc-localbot/blob/main/system/control/shutdown.sh"
    click Notebook "https://github.com/lelekhoa1812/aitc-localbot/blob/main/build/buildup.ipynb"
    click Resolver "https://github.com/lelekhoa1812/aitc-localbot/blob/main/script/resolver.py"
    click RawPDF "https://github.com/lelekhoa1812/aitc-localbot/tree/main/cataloges/"
```
