# muralimanohar2906/mailwatch architecture

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

- Interactive diagram: https://gitdiagram.com/muralimanohar2906/mailwatch
- Repository: https://github.com/muralimanohar2906/mailwatch

## Overview

##### Project type and purpose
- This is a full-stack prototype combining a browser extension (Chrome) with a local ML-powered backend (FastAPI).
- Purpose: detect scam/phishing emails in Gmail/Outlook Web by sending email content to a local AI service and overlaying a risk banner in the browser.

##### File structure
Top-level:
- extension/ – Chrome extension code (manifest.json, content/background scripts, popup UI)
- server/    – Python FastAPI app, dataset scripts, model artifacts, training & evaluation
- README.md, requirements.txt, scan_logs.csv – project‐wide documentation and data
server/ deeper:
- prepare_dataset.py, combine_datasets.py – dataset ingestion & cleaning
- train_model.py – trains TF-IDF + Logistic Regression, outputs vectorizer.joblib & classifier.joblib
- evaluate_model.py – model evaluation
- server.py – FastAPI app exposing an inference endpoint
- *.csv – raw & combined email datasets
- *.joblib – serialized model artifacts

##### Key insights from README
- Frontend: content.js injects banner; background.js handles messaging; popup.js shows controls.
- Backend: FastAPI service running on localhost:8000, responds with scam probability.
- ML pipeline: TF-IDF vectorizer + Logistic Regression, retrainable locally.

##### Main components
a. Browser Extension (Frontend)
- Content Script (content.js)
- Background Script (background.js)
- Popup UI (popup.html + popup.js)
b. Local Inference Service (Backend)
- FastAPI server (server.py)
- Model artifacts (vectorizer.joblib, classifier.joblib)
c. Data Pipeline (Offline ML Pipeline)
- Data preparation & combination (prepare_dataset.py, combine_datasets.py)
- Model training (train_model.py)
- Model evaluation (evaluate_model.py)
d. Datasets & Logs
- Raw CSVs (e.g., phishing_email.csv, Enron.csv, etc.)
- Combined/processed datasets (emails_combined.csv, emails_labeled.csv)
- scan_logs.csv for usage logging

##### Relationships and interactions
- Browser Extension → collects email subject/body → sends HTTP POST to FastAPI endpoint
- FastAPI Server → loads vectorizer & classifier → returns JSON { probability, label }
- Extension → receives response → injects a banner in Gmail/Outlook UI
- Offline Pipeline (separate script executions) → reads raw CSVs → outputs model artifacts

##### Architectural patterns & principles
- Separation of concerns: UI (extension) vs. inference (backend) vs. data pipeline (scripts)
- Plug-and-play ML: model artifacts live separately, can be retrained/replaced
- Local privacy: no external requests, all inference on-device

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Extension"
        manifest["manifest.json"]:::blue
        content["content.js"]:::blue
        background["background.js"]:::blue
        popupHTML["popup.html"]:::blue
        popupJS["popup.js"]:::blue
    end

    subgraph "FastAPI Inference Service"
        server["server.py"]:::green
        vectorizer["vectorizer.joblib"]:::storage
        classifier["classifier.joblib"]:::storage
    end

    subgraph "Offline ML Pipeline"
        rawDatasets["Raw Email CSVs"]:::storage
        prepare["prepare_dataset.py"]:::orange
        combine["combine_datasets.py"]:::orange
        combined["emails_combined.csv"]:::storage
        labeled["emails_labeled.csv"]:::storage
        train["train_model.py"]:::orange
        evaluate["evaluate_model.py"]:::orange
    end

    scanLogs["scan_logs.csv"]:::storage

    %% Connections: Extension to Inference
    content -->|"POST /predict {subject, body}"| server
    server -->|"{probability, label}"| content
    background --> content
    popupJS --> background
    popupHTML --> popupJS

    %% Server loads models and logs
    vectorizer --> server
    classifier --> server
    server --> scanLogs

    %% Offline pipeline flow
    rawDatasets --> prepare
    rawDatasets --> combine
    prepare --> combined
    combine --> labeled
    labeled --> train
    labeled --> evaluate
    train --> vectorizer
    train --> classifier

    %% Click Events
    click manifest "https://github.com/muralimanohar2906/mailwatch/blob/main/extension/manifest.json"
    click content "https://github.com/muralimanohar2906/mailwatch/blob/main/extension/content.js"
    click background "https://github.com/muralimanohar2906/mailwatch/blob/main/extension/background.js"
    click popupHTML "https://github.com/muralimanohar2906/mailwatch/blob/main/extension/popup.html"
    click popupJS "https://github.com/muralimanohar2906/mailwatch/blob/main/extension/popup.js"
    click server "https://github.com/muralimanohar2906/mailwatch/blob/main/server/server.py"
    click vectorizer "https://github.com/muralimanohar2906/mailwatch/blob/main/server/vectorizer.joblib"
    click classifier "https://github.com/muralimanohar2906/mailwatch/blob/main/server/classifier.joblib"
    click prepare "https://github.com/muralimanohar2906/mailwatch/blob/main/server/prepare_dataset.py"
    click combine "https://github.com/muralimanohar2906/mailwatch/blob/main/server/combine_datasets.py"
    click train "https://github.com/muralimanohar2906/mailwatch/blob/main/server/train_model.py"
    click evaluate "https://github.com/muralimanohar2906/mailwatch/blob/main/server/evaluate_model.py"
    click rawDatasets "https://github.com/muralimanohar2906/mailwatch/blob/main/server/CEAS_08.csv"
    %% rawDatasets is a grouping; point to one file as representative
    click combined "https://github.com/muralimanohar2906/mailwatch/blob/main/server/emails_combined.csv"
    click labeled "https://github.com/muralimanohar2906/mailwatch/blob/main/server/emails_labeled.csv"
    click scanLogs "https://github.com/muralimanohar2906/mailwatch/blob/main/scan_logs.csv"

    %% Styles
    classDef blue fill:#D6E9FE,stroke:#4D7EBB
    classDef green fill:#D6F5D6,stroke:#4DAF4D
    classDef orange fill:#FFF2CC,stroke:#E6B800
    classDef storage fill:#F0F0F0,stroke:#999 color:#333

    class manifest,content,background,popupHTML,popupJS blue
    class server green
    class prepare,combine,train,evaluate orange
    class rawDatasets,combined,labeled,vectorizer,classifier,scanLogs storage
```
