How muralimanohar2906/mailwatch works
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