# ananya-vastare/scamslam architecture

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

- Interactive diagram: https://gitdiagram.com/ananya-vastare/scamslam
- Repository: https://github.com/ananya-vastare/scamslam

## Overview

##### Project type and purpose
- ScamSlam is a full-stack web application (built in Python/Flask) whose purpose is real-time phishing detection for URLs, emails, and QR codes by combining rule-based heuristics with a trained machine-learning model.

##### File structure
- Top-level files:
- app.py – the Flask application entry point and routing logic
- model.py – code to load and invoke the ML model and vectorizer
- requirements.txt – Python dependencies (Flask, scikit-learn, etc.)
- sms_model.pkl & sms_vectorizer.pkl – serialized ML artifacts
- spam.csv & SMSSpamCollection – sample/train data for the ML pipeline
- Directories:
- templates/ – Jinja2 HTML templates (HomePage.html, MainHub.html, Pagenotfound.html)
- static/ – front-end assets:
– js/ (homepage.js, mainpage.js)
– images/
– music/ (alert/success audio cues)

##### README for additional insights
- The detection engine exposes multiple flows: URL checks, email text analysis, QR code scanning.
- Privacy-focused: no data persisted beyond in-memory processing.
- Responsive, minimalist UI served by Flask’s template/static architecture.

##### Main components and interactions
a. Components
- Web Browser (User Interface)
- Frontend Assets (HTML templates + CSS/JS under static/)
- Flask Web Server (app.py)
- Phishing Detection Service
– Rule-Based Engine (blacklist lookups, heuristics)
– ML Model Pipeline (vectorizer + classifier loaded from .pkl)
- External Services (if any – e.g., QR code library or third-party blacklist API)
- Data Store (optional – sample data CSV, but in production none persists user data)
b. Relationships and data flow
1. User submits URL/email/QR through the browser UI
2. Request hits Flask endpoints in app.py
3. Flask routes dispatch to either rule-based checks or ML model (via model.py)
4. model.py loads and applies sms_vectorizer.pkl → sms_model.pkl
5. Decision returned to Flask → Flask renders JSON or injects result into MainHub.html
6. Browser displays result and plays appropriate audio cue (Success.mp3 or Alert.mp3)
c. Architectural patterns/design principles
- MVC-like separation:
– View layer (templates + static)
– Controller layer (app.py routes)
– Model layer (model.py + ML artifacts)
- Single process monolith (all functions in one Flask app)
- Real-time stateless request processing (privacy-focused)
d. Key technologies/frameworks
- Python 3.x, Flask
- scikit-learn (machine-learning pipeline)
- Jinja2 templating
- Vanilla JavaScript for client interactivity
- HTML5/CSS3 (responsive design)
- Optional: pyzbar or similar for QR code parsing

##### Elements
- Labels:
- “Browser / User Interface”
- “Flask Server (app.py)”
- “Rule-Based Engine”
- “ML Model Pipeline”
- “External Blacklist API”, “QR Code Library” (if applicable)
- Request flows from UI → Flask
- Internal calls from Flask → Rule Engine / Model Pipeline
- Responses from engines → Flask → UI
- Rectangles for components (frontend/backend/ML)

##### Final recommendations
- Be very detailed: break the Flask app into “Routing Layer” and “Service Layer” if desired.
- Sample data files (.csv) off to the side under “Development / Training Resources.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser / User Interface"]:::frontend

    subgraph "Frontend Assets"
        HomePage["HomePage.html"]:::frontend
        MainHub["MainHub.html"]:::frontend
        Pagenotfound["Pagenotfound.html"]:::frontend
        HomepageJS["homepage.js"]:::frontend
        MainpageJS["mainpage.js"]:::frontend
        Images["static/images/"]:::frontend
        Music["static/music/"]:::frontend
    end

    subgraph "Backend Layer"
        App["Flask Server (app.py)"]:::backend
        RuleEngine["Rule-Based Engine"]:::backend
        MLService["ML Model Pipeline"]:::ml
        Vectorizer["sms_vectorizer.pkl"]:::ml
        Classifier["sms_model.pkl"]:::ml
    end

    subgraph "External Services"
        BlacklistAPI["External Blacklist API"]:::external
        QRLibrary["QR Code Library"]:::external
    end

    subgraph "Dev / Training Resources"
        SpamCSV["spam.csv"]:::resource
        SMSCol["SMSSpamCollection"]:::resource
        Req["requirements.txt"]:::resource
    end

    %% Flow
    Browser --> HomePage
    Browser --> MainHub
    Browser --> Pagenotfound
    Browser --> HomepageJS
    Browser --> MainpageJS
    Browser --> Images
    Browser --> Music
    Browser -->|"submits request"| App

    App -->|invokes| RuleEngine
    App -->|invokes| MLService
    MLService --> Vectorizer
    MLService --> Classifier
    RuleEngine -->|queries| BlacklistAPI
    App -->|uses| QRLibrary
    App -->|"returns response"| Browser

    %% Click Events
    click HomePage "https://github.com/ananya-vastare/scamslam/blob/main/templates/HomePage.html"
    click MainHub "https://github.com/ananya-vastare/scamslam/blob/main/templates/MainHub.html"
    click Pagenotfound "https://github.com/ananya-vastare/scamslam/blob/main/templates/Pagenotfound.html"
    click HomepageJS "https://github.com/ananya-vastare/scamslam/blob/main/static/js/homepage.js"
    click MainpageJS "https://github.com/ananya-vastare/scamslam/blob/main/static/js/mainpage.js"
    click Images "https://github.com/ananya-vastare/scamslam/tree/main/static/images/"
    click Music "https://github.com/ananya-vastare/scamslam/tree/main/static/music/"
    click App "https://github.com/ananya-vastare/scamslam/blob/main/app.py"
    click Vectorizer "https://github.com/ananya-vastare/scamslam/blob/main/sms_vectorizer.pkl"
    click Classifier "https://github.com/ananya-vastare/scamslam/blob/main/sms_model.pkl"
    click SpamCSV "https://github.com/ananya-vastare/scamslam/blob/main/spam.csv"
    click SMSCol "https://github.com/ananya-vastare/scamslam/tree/main/SMSSpamCollection"
    click Req "https://github.com/ananya-vastare/scamslam/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#FFDFA8,stroke:#333,stroke-width:1px;
    classDef backend fill:#C8E6C9,stroke:#333,stroke-width:1px;
    classDef ml fill:#BBDEFB,stroke:#333,stroke-width:1px;
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px;
    classDef resource fill:#E1BEE7,stroke:#333,stroke-width:1px;
```
