# adarshh9/nutriai architecture

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

- Interactive diagram: https://gitdiagram.com/adarshh9/nutriai
- Repository: https://github.com/adarshh9/nutriai

## Overview

##### Project Type and Purpose
- Full-stack web application for personalized nutrition recommendations
- Combines multiple AI subsystems (Knowledge Graph, GNN, Text Retrieval, LLM explanations, RL cache) behind a Flask frontend

##### File Structure
- core/Flask – Flask app entrypoint (main.py, app.py), configurations, templates (HTML)
- core/kg_inference – Knowledge graph loader & query logic, CSV/PKL data
- core/gnn_inference – Pretrained GNN model and inference code
- core/text_Retrieval – FAISS index and text-retrieval logic
- core/*.ipynb – Notebooks (development/experimentation)
- dataset/ – Raw CSV/Excel nutritional and food-disease data
- experiments/ – Prototype apps and scripts (not part of production)

##### README Insights
- Emphasis on multi-model aggregation, scientific evidence retrieval, LLM explanation, RL-based caching, and visualization

##### Main Components
A. User Interface (Web UI)
– Flask routes & HTML templates (index.html, results.html, cache.html)
B. Flask Web Server (Orchestrator)
– Receives HTTP requests, normalizes input, coordinates subcomponents
C. Knowledge Graph Module
– core/kg_inference/kg.py, data files (kg_data.csv, nutrient_data.csv, etc.)
D. Graph Neural Network Module
– core/gnn_inference/gnn.py, model checkpoint (gnn_model.pt)
E. Text Retrieval Module
– core/text_Retrieval/tr.py, FAISS index, metadata
F. LLM Explanation Service
– Groq LLama-3-70B API client
G. Reinforcement Learning Cache
– Q-learning code, persistence (nutriai_cache.json)
H. Visualization Component
I. Data Sources & Storage
– dataset folder, PKL/CSV/Excel files
J. External Services
– Groq API, optional data stores for persistence

##### Interactions and Data Flow
1. User → (HTTP) → Flask
2. Flask → [KG module] → KG results
3. Flask → [GNN module] → Novel predictions
4. Flask → [Text Retrieval] → Evidence snippets
5. Flask aggregates → Intermediate “Results”
6. Flask → [RL Cache] checks for explanation
- Cache hit → retrieve explanation
- Cache miss → call Groq API → receive explanation → feed back to RL cache
7. Flask → [Visualization] when requested → generate graph
8. Flask → Format full response → HTML/JSON → UI → User

##### Architectural Patterns and Principles
- Modular separation of concerns (KG, GNN, TextR, LLM, Cache, Viz)
- Central orchestrator (Flask) following an MVC-like flow
- Data-driven modules reading from common dataset store
- Asynchronous or parallel calls to inference modules (for performance)
- RL-based dynamic caching for optimization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and UI
    User["User"]:::external
    subgraph "Frontend"
        direction TB
        Index["index.html"]:::frontend
        Results["results.html"]:::frontend
        CachePage["cache.html"]:::frontend
        Base["base.html"]:::frontend
    end

    %% Backend Orchestrator
    subgraph "Backend"
        direction TB
        Main["main.py"]:::backend
        Configs["configs.py"]:::backend
        App["app.py"]:::backend
    end

    %% Inference Modules
    subgraph "Inference Modules"
        direction TB
        subgraph "Knowledge Graph Module"
            KGModule["kg.py\n(kg_data.csv,\nnutrient_data.csv,\ndf_extra.csv,\nfood_matching_data.pkl)"]:::inference
        end
        subgraph "GNN Module"
            GNNModule["gnn.py\n(gnn_model.pt,\ngnn_assets.pkl)"]:::inference
        end
        subgraph "Text Retrieval Module"
            TRModule["tr.py\n(faiss index,\nmetadata.pkl,\n texts.pkl,\npubmed_abstracts.json)"]:::inference
        end
    end

    %% RL Cache
    subgraph "Cache & Optimization"
        direction TB
        RLCache["RL Cache\n(.nutriai_cache.json)"]:::cache
    end

    %% Visualization
    Viz["Visualization\n(NetworkX)"]:::inference

    %% Data Sources
    subgraph "Data Sources"
        direction TB
        Datasets[(Dataset Files)]:::data
    end

    %% External Services
    Groq["Groq LLaMA-3-70B API"]:::external

    %% Flows
    User -->|"HTTP Request"| Index
    Index -->|"renders via Flask"| Main
    Results --> Main
    CachePage --> Main
    Base --> Main

    Main -->|"query: disease"| KGModule
    Main -->|"input vector"| GNNModule
    Main -->|"query terms"| TRModule
    Main -->|"check cache"| RLCache
    RLCache -->|Cache Hit| Main
    RLCache -->|Cache Miss| Groq
    Groq -->|Explanation| RLCache
    Main -->|"assemble results"| Viz
    Viz --> Main
    Main -->|"response: HTML/JSON"| Results
    Main -->|"response: cache view"| CachePage

    KGModule --> Datasets
    GNNModule --> Datasets
    TRModule --> Datasets

    %% Click Events
    click Index "https://github.com/adarshh9/nutriai/blob/main/core/Flask/templates/index.html"
    click Results "https://github.com/adarshh9/nutriai/blob/main/core/Flask/templates/results.html"
    click CachePage "https://github.com/adarshh9/nutriai/blob/main/core/Flask/templates/cache.html"
    click Base "https://github.com/adarshh9/nutriai/blob/main/core/Flask/templates/base.html"
    click Main "https://github.com/adarshh9/nutriai/blob/main/core/Flask/main.py"
    click Configs "https://github.com/adarshh9/nutriai/blob/main/core/Flask/configs.py"
    click App "https://github.com/adarshh9/nutriai/blob/main/core/app.py"
    click KGModule "https://github.com/adarshh9/nutriai/blob/main/core/kg_inference/kg.py"
    click GNNModule "https://github.com/adarshh9/nutriai/blob/main/core/gnn_inference/gnn.py"
    click TRModule "https://github.com/adarshh9/nutriai/blob/main/core/text_Retrieval/tr.py"
    click RLCache "https://github.com/adarshh9/nutriai/blob/main/core/.nutriai_cache.json"
    click Datasets "https://github.com/adarshh9/nutriai/blob/main/dataset/full_dataset.csv"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#3399FF,color:#000
    classDef backend fill:#E8E8E8,stroke:#999,color:#000
    classDef inference fill:#DFF2DD,stroke:#33AA33,color:#000
    classDef cache fill:#FFF4CC,stroke:#FFCC00,color:#000
    classDef data fill:#FFE6CC,stroke:#FF9900,color:#000
    classDef external fill:#F0E0FF,stroke:#9933CC,color:#000
```
