# wasifsohail5/spamshield architecture

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

- Interactive diagram: https://gitdiagram.com/wasifsohail5/spamshield
- Repository: https://github.com/wasifsohail5/spamshield

## Overview

##### Project type and purpose
- This is a machine-learning-powered web application (“Spam Shield”) for classifying emails as spam or ham.
- It consists of two logical pieces: an ML pipeline (data preprocessing, feature extraction, model training) and a real-time inference service (Streamlit app).

##### File structure
- Top-level scripts:
- Preprocessor.py – text cleaning & TF-IDF feature extraction
- app.py – Streamlit front-end for user input & model inference
- Spam E-Mail Detctor(ML).ipynb – Jupyter Notebook for experimentation & model training
- Model artifacts:
- vectorizer.joblib – serialized TF-IDF vectorizer
- rf_model.joblib, nb_model.joblib, spam_model.joblib – trained classifiers
- Config:
- requirements.txt – Python dependencies
- .devcontainer/ – dev-container config
- assets:
- screenshots/ – UI mockups

##### README for additional insights
- Three algorithms (Logistic Regression, Naïve Bayes, Random Forest) are trained offline, evaluated, and the best saved.
- Streamlit app loads the saved artifacts in real time.
- No external databases or cloud services—everything runs locally or on a single server/container.

##### Main components and interactions
a. Data Ingestion & Preprocessing (offline)
- Raw email dataset → Preprocessor.py / Notebook → cleaned tokens
- TF-IDF Vectorizer → vectorizer.joblib
b. Model Training & Evaluation (offline)
- Preprocessed features → train three models → evaluate → choose best → export .joblib
c. Model Repository
- vectorizer.joblib + best_model.joblib (spam_model.joblib) stored on disk
d. Streamlit Inference Service (app.py)
- User inputs email in browser → app loads vectorizer & model → transforms text → predicts spam/ham → displays result
e. Developer Environment
- .devcontainer for reproducible setup

##### Architectural patterns and design principles
- Separation of offline ML pipeline vs. online service
- Single responsibility: Preprocessing, Training, and Inference are separate modules
- Artifact repository on filesystem (could evolve into S3 or model registry)
- Stateless web app: no session or DB needed

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Storage
    Dataset["Raw Email Dataset"]:::storage

    %% Offline Pipeline
    subgraph "Offline Pipeline"
        direction TB
        Preprocessor["Preprocessing Module\n(Preprocessor.py)"]:::offline
        Notebook["Preprocessing & Training Notebook\n(Spam E-Mail Detector(ML).ipynb)"]:::offline
        Trainer["Model Trainer"]:::offline
    end

    %% Model Artifacts
    subgraph "Model Artifacts"
        direction TB
        Vectorizer["TF-IDF Vectorizer\n(vectorizer.joblib)"]:::artifacts
        NBModel["Naïve Bayes Model\n(nb_model.joblib)"]:::artifacts
        RFModel["Random Forest Model\n(rf_model.joblib)"]:::artifacts
        BestModel["Best Model (Spam Classifier)\n(spam_model.joblib)"]:::artifacts
    end

    %% Online Inference
    subgraph "Online Inference"
        direction TB
        StreamlitApp["Streamlit Web App\n(app.py)"]:::online
        Browser["User Browser"]:::online
    end

    %% Dev Environment
    subgraph "Dev Environment"
        direction TB
        DevContainer["Dev Container Config\n(.devcontainer/devcontainer.json)"]:::dev
        Requirements["Project Dependencies\n(requirements.txt)"]:::dev
    end

    %% Connections
    Dataset --> Preprocessor
    Preprocessor --> Notebook
    Preprocessor --> Trainer
    Notebook --> Trainer
    Preprocessor --> Vectorizer
    Vectorizer --> Trainer
    Trainer --> NBModel
    Trainer --> RFModel
    Trainer --> BestModel
    Vectorizer --> StreamlitApp
    BestModel --> StreamlitApp
    NBModel --> StreamlitApp
    RFModel --> StreamlitApp
    StreamlitApp --> Browser

    %% Environment Dependencies
    DevContainer -.-> Preprocessor
    DevContainer -.-> Trainer
    DevContainer -.-> StreamlitApp
    Requirements -.-> Preprocessor
    Requirements -.-> Trainer
    Requirements -.-> StreamlitApp

    %% Click Events
    click Preprocessor "https://github.com/wasifsohail5/spamshield/blob/main/Preprocessor.py"
    click Notebook "https://github.com/wasifsohail5/spamshield/blob/main/Spam E-Mail Detctor(ML).ipynb"
    click Vectorizer "https://github.com/wasifsohail5/spamshield/blob/main/vectorizer.joblib"
    click NBModel "https://github.com/wasifsohail5/spamshield/blob/main/nb_model.joblib"
    click RFModel "https://github.com/wasifsohail5/spamshield/blob/main/rf_model.joblib"
    click BestModel "https://github.com/wasifsohail5/spamshield/blob/main/spam_model.joblib"
    click StreamlitApp "https://github.com/wasifsohail5/spamshield/blob/main/app.py"
    click DevContainer "https://github.com/wasifsohail5/spamshield/blob/main/.devcontainer/devcontainer.json"
    click Requirements "https://github.com/wasifsohail5/spamshield/blob/main/requirements.txt"

    %% Styles
    classDef offline fill:#D0E7FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef artifacts fill:#E2F7E1,stroke:#28a745,color:#28a745,stroke-width:1px;
    classDef online fill:#FFE7D0,stroke:#d2691e,color:#d2691e,stroke-width:1px;
    classDef storage fill:#F0F0F0,stroke:#666666,color:#333333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef dev fill:#F8F9FA,stroke:#6a737d,color:#6a737d,stroke-width:1px,stroke-dasharray: 5 5;
```
