# eragon-amansirohi/hea_qa architecture

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

- Interactive diagram: https://gitdiagram.com/eragon-amansirohi/hea_qa
- Repository: https://github.com/eragon-amansirohi/hea_qa

## Overview

##### Project type and purpose
- HEA_QA is a full‑stack web application for Retrieval‑Augmented Generation (RAG) question answering on research abstracts about High Entropy Alloys.
- The user interface is served by Flask; the core functionality is chunking, embedding, storing context, and generating answers via either a local fine‑tuned language model (Phi‑2 QLoRA) or an API-based model (DeepSeek/OpenAI).

##### File structure
- Top level:
- app.py – Flask application entry point
- qa_pair_gen.py – standalone script for generating QA pairs
- requirements.txt, README.md, LICENSE
- models/phi2-lora-finetuned – local LLM adapter files
- static/ – front‑end assets (css, js)
- templates/index.html – main HTML template
- test/ – sample CSV and TXT for upload
- Patterns and modules:
- MVC‑like separation: templates (views), static (assets), app.py (controller), models (ML resources), scripts
- Storage/config: Flask sessions & pickle, FAISS index persists in memory or pickled storage
- Build/deploy: minimal (python app.py), configurable via requirements.txt

##### README for additional insights
- Uses FAISS for vector search and SentenceTransformer for embeddings
- Switchable model layer abstraction (local vs. API)
- Persistent document store via Flask sessions & pickle
- QA pair generation is run in background by qa_pair_gen.py

a. Main components:
- Client Browser (UI)
- Flask Web Server (app.py)
- Frontend Static & Templates
- Document Store (Flask sessions + pickle files)
- Embedding Service (SentenceTransformer)
- Vector Index (FAISS)
- Model Routing Layer
– Local Model: Phi‑2 QLoRA adapter
– External API: DeepSeek/OpenAI
- QA Pair Generation Module (qa_pair_gen.py)
- Optional Storage: CSV/JSON upload
b. Relationships & interactions:
1. User → Browser UI: submit abstract or upload CSV
2. Browser → Flask endpoint: POST abstract
3. Flask → Embedding Service: chunk & embed text
4. Embeddings → FAISS: add to/inquire from index
5. Flask persists raw text & index references in session (pickle)
6. User asks question → Flask retrieves relevant chunks via FAISS
7. Flask routes to local model or API model
8. Model returns answer → Flask sends JSON → UI displays
9. QA Pair Gen module can be invoked by Flask or run separately
c. Architectural patterns & design principles:
- Modular separation: web layer, ML layer, storage layer
- Strategy pattern for switching between local and API models
- RAG pipeline: chunk → embed → index → retrieve → generate
- Persistent session management for user state
d. Key technologies:
- Flask, Jinja2
- Python: transformers, peft, sentence-transformers, faiss-cpu, flask-session
- Frontend: HTML/CSS/JavaScript (static/js/script.js, static/css/style.css)

##### Final advice
- Do not over‑complicate: a clear 4‑layer view (UI → Web Server → ML Services → Storage) plus the model router suffices

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (UI)" 
        direction TB
        HTML["index.html"]:::ui
        CSS["style.css"]:::ui
        JS["script.js"]:::ui
    end

    Client["Client Browser"]:::ui

    Client -->|"loads UI"| HTML
    HTML -->|"references"| CSS
    HTML -->|"references"| JS
    Client -->|"submit abstract / question"| App

    %% Web Server Layer
    subgraph "Web Server (Flask API)" 
        direction TB
        App["app.py"]:::web
        Req["requirements.txt"]:::web
    end

    App -->|"imports libs"| Req
    App -->|"chunk & embed text"| Embed
    App -->|"persist session & index"| Session
    App -->|"retrieve chunks"| FAISS
    App -->|"route to model"| Router
    App -->|"return answer"| Client

    %% ML Services Layer
    subgraph "ML Services" 
        direction TB
        Embed["Embedding Service\n(SentenceTransformer)"]:::ml
        FAISS["Vector Index\n(FAISS)"]:::ml
        Router["Model Router"]:::ml
        subgraph "Models"
            direction TB
            Local["Local Model\n(Phi-2 QLoRA)"]:::ml
            External["External API\n(DeepSeek/OpenAI)"]:::ml
        end
    end

    %% Storage Layer
    subgraph "Storage & Persistence" 
        direction TB
        Session["Session Store\n(pickle)"]:::storage
        Upload["Uploaded Files"]:::storage
        Session -->|"stored index refs"| FAISS
        Upload -->|"sample uploads"| QAgen
    end

    %% QA Pair Generation Module
    subgraph "QA Pair Generation" 
        direction TB
        QAgen["qa_pair_gen.py"]:::script
    end

    QAgen -->|"uses Embedding & Router"| Embed
    QAgen -->|"reads samples"| Upload

    %% Model routing connections
    Router -->|"local inference"| Local
    Router -->|"API call"| External
    Local -->|"answer"| App
    External -->|"answer"| App

    %% Web server to storage
    App -->|"save raw text"| Session

    %% Click Events
    click HTML "https://github.com/eragon-amansirohi/hea_qa/blob/main/templates/index.html"
    click CSS "https://github.com/eragon-amansirohi/hea_qa/blob/main/static/css/style.css"
    click JS "https://github.com/eragon-amansirohi/hea_qa/blob/main/static/js/script.js"
    click App "https://github.com/eragon-amansirohi/hea_qa/blob/main/app.py"
    click Req "https://github.com/eragon-amansirohi/hea_qa/blob/main/requirements.txt"
    click Local "https://github.com/eragon-amansirohi/hea_qa/tree/main/models/phi2-lora-finetuned/"
    click QAgen "https://github.com/eragon-amansirohi/hea_qa/blob/main/qa_pair_gen.py"
    click Upload "https://github.com/eragon-amansirohi/hea_qa/blob/main/test/test.csv"
    click Upload "https://github.com/eragon-amansirohi/hea_qa/blob/main/test/test.txt"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef web fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef ml fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef script fill:#FFFACD,stroke:#333,stroke-width:1px
```
