# satwik77-dev/uf-eee6778-fall25-termproject architecture

> Architecture diagram of the GitHub repository satwik77-dev/uf-eee6778-fall25-termproject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satwik77-dev/uf-eee6778-fall25-termproject
- Repository: https://github.com/satwik77-dev/uf-eee6778-fall25-termproject

## Overview

##### Project Type & Purpose
- ClaimVerify is a full-stack AI-powered fact-verification system.
- It ingests user claims via a Streamlit UI, runs an inference pipeline combining offline fact-check databases (PolitiFact, Snopes) with real-time Google search fallbacks, and returns verdicts plus interpretability insights.

##### Top-Level Components
a. UI Layer
- streamlit_app.py
- Theme assets (dark_theme.css, light_theme.css)
b. Backend Inference Pipeline
- src/preprocess.py: Text cleaning & harmonization
- src/embeddings.py: Sentence-BERT embedding generation
- src/retrieval.py: FAISS index search + Google API fallback
- src/model.py: Classifier loading & inference (RoBERTa fine-tuned)
- src/explainability.py: SHAP interpretability
- src/inference_pipeline.py: Orchestrator that ties modules together
c. Data Storage
- data/raw/: Original PolitiFact & Snopes datasets
- data/processed/: Cleaned/merged CSV, .npy/.pkl embeddings, FAISS index & metadata
d. Model Artifacts
- models/classifier/roberta_finetuned/: Model checkpoints, tokenizer, label mapping, temperature scaling
e. External Services
- Google Custom Search API (for live fact-check articles)
f. Supporting Notebooks & Reports
- notebooks/: EDA, offline retrieval, training
- DeliverableReports/ & results/: Documentation & plots

##### Relationships & Data Flow
- User enters claim → UI Layer
→ UI calls Inference Pipeline API (local function call in Streamlit)
→ Preprocess cleans claim text
→ Embeddings module encodes to semantic vectors
→ Retrieval searches FAISS index (offline_db).
- If no match above threshold → trigger Google API search
→ Classification model predicts credibility label
→ Explainability module generates SHAP visuals
→ Pipeline returns: similar claims, verdict, confidence, interpretability plots
→ UI renders results

##### Architectural Patterns & Design Principles
- Layered Architecture: Presentation (Streamlit), Application (inference modules), Data (processed datasets, indices)
- Modular Code: Each src/*.py implements one concern
- Reusable Artifacts: Precomputed embeddings & FAISS index for performance
- Failover Strategy: Offline-first with API fallback for resilience
- Separation of Concerns: Notebooks for exploration; src/ for production logic; ui/ for front-end

##### Key Technologies & Frameworks
- Python 3.9+
- Streamlit (UI)
- Sentence-BERT (embeddings)
- FAISS (vector search)
- HuggingFace Transformers (RoBERTa)
- SHAP (interpretability)
- Pandas, NumPy (data processing)
- Google Custom Search API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        UIApp["Streamlit App"]:::ui
        DarkTheme["dark_theme.css"]:::ui
        LightTheme["light_theme.css"]:::ui
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        Orchestrator["inference_pipeline.py"]:::pipeline
        Preprocess["data_preprocess.py"]:::pipeline
        Embeddings["embeddings.py"]:::pipeline
        Retrieval["retrieval.py"]:::pipeline
        Classification["model.py"]:::pipeline
        Explainability["explainability.py"]:::pipeline
    end

    %% Data Storage
    subgraph "Data Storage"
        RawData[(Raw Data\ndata/raw/)]:::datastore
        subgraph "Processed Data"
            MergedCSV[(merged_factcheck_dataset.csv)]:::datastore
            CleanedCSV[(merged_factcheck_datasetcleaned.csv)]:::datastore
            subgraph "Embeddings Files"
                ClaimNpy[(claim_embeddings.npy)]:::datastore
                ClaimPkl[(claim_embeddings.pkl)]:::datastore
                MetadataCSV[(claim_metadata.csv)]:::datastore
            end
            subgraph "FAISS Index"
                IndexBin[(claimverify_faiss_index.bin)]:::datastore
                IndexMetaCSV[(claimverify_faiss_metadata.csv)]:::datastore
            end
        end
    end

    %% Model Artifacts
    ModelArtifacts[(RoBERTa Fine-tuned\nmodels/classifier/roberta_finetuned/)]:::model

    %% External Service
    External["Google Custom Search API"]:::external

    %% Supporting Notebooks & Reports
    subgraph "Auxiliary Resources"
        Notebooks[(notebooks/)]:::aux
        Reports[(DeliverableReports/)]:::aux
        ArchDocs[(Architecture/)]:::aux
        Results[(results/)]:::aux
    end

    %% Data Flow
    UIApp -->|"claim text"| Orchestrator
    Orchestrator -->|"text cleaning"| Preprocess
    Preprocess -->|"clean text"| Embeddings
    Embeddings -->|"embedding vector"| Retrieval
    Retrieval -->|"offline search"| MergedCSV
    Retrieval -->|"if no offline match → search"| External
    Retrieval -->|"search results"| Orchestrator
    Orchestrator -->|"to classify"| Classification
    Classification -->|"credibility label"| Explainability
    Explainability -->|"interpretability plots"| Orchestrator
    Orchestrator -->|"verdict + plots"| UIApp

    %% Click Events
    click UIApp "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/ui/streamlit_app.py"
    click DarkTheme "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/ui/assets/dark_theme.css"
    click LightTheme "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/ui/assets/light_theme.css"
    click Preprocess "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/src/data_preprocess.py"
    click Embeddings "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/src/embeddings.py"
    click Retrieval "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/src/retrieval.py"
    click Classification "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/src/model.py"
    click Explainability "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/src/explainability.py"
    click Orchestrator "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/src/inference_pipeline.py"
    click RawData "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/tree/main/data/raw/"
    click MergedCSV "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/data/processed/merged_factcheck_dataset.csv"
    click CleanedCSV "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/data/processed/merged_factcheck_datasetcleaned.csv"
    click ClaimNpy "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/data/processed/embeddings/claim_embeddings.npy"
    click ClaimPkl "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/data/processed/embeddings/claim_embeddings.pkl"
    click MetadataCSV "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/data/processed/embeddings/claim_metadata.csv"
    click IndexBin "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/data/processed/faiss_index/claimverify_faiss_index.bin"
    click IndexMetaCSV "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/blob/main/data/processed/faiss_index/claimverify_faiss_metadata.csv"
    click ModelArtifacts "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/tree/main/models/classifier/roberta_finetuned/"
    click Notebooks "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/tree/main/notebooks/"
    click Reports "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/tree/main/DeliverableReports/"
    click ArchDocs "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/tree/main/Architecture/"
    click Results "https://github.com/satwik77-dev/uf-eee6778-fall25-termproject/tree/main/results/"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef pipeline fill:#E6FFEB,stroke:#28a745,color:#22863a,stroke-dasharray: 5 5;
    classDef datastore fill:#FFF5E6,stroke:#d9730d,color:#d9730d;
    classDef model fill:#F3E6FF,stroke:#6f42c1,color:#6f42c1;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d,stroke-dasharray: 2 2;
    classDef aux fill:#FFE6F0,stroke:#cb2431,color:#cb2431;
```
