# gaurav241/email-sms-spam-classifier architecture

> Architecture diagram of the GitHub repository gaurav241/email-sms-spam-classifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gaurav241/email-sms-spam-classifier
- Repository: https://github.com/gaurav241/email-sms-spam-classifier

## Overview

This repository is a small, self-contained machine-learning web application with two clear subsystems:

1. an offline model-building pipeline
2. an online Streamlit inference app

#### 1) High-level architecture

The app classifies a user-entered SMS or email message as either spam or not spam. The key architectural pattern is:

- **Training is done ahead of time**
- **Inference happens at runtime in the Streamlit app**
- **The trained artifacts are persisted as pickle files and loaded by the UI**

There is no separate API service, database, message queue, or authentication layer in the repository. The deployment is a single-process Python web app centered around `app.py`.

#### 2) Main repository components

##### A. User-facing application
**`app.py`**
- This is the runtime entry point.
- It likely builds the Streamlit UI, accepts text input, loads the serialized model artifacts, and returns a classification result.
- It also appears to handle presentation of the result state shown in the screenshots:
  - home page
  - spam result
  - not-spam result

**`visuals/ss`**
- Contains screenshots used in the README and likely reflects the UI states of the Streamlit app.
- This is documentation/supporting content rather than part of runtime behavior.

##### B. Machine learning artifacts
**`model.pkl`**
- Serialized trained classifier.
- Based on the README, the model is a **Naive Bayes classifier**.

**`vectorizer.pkl`**
- Serialized text feature extractor used to convert raw message text into the numeric representation expected by the model.
- This is a critical boundary object: the app cannot classify text without applying the same vectorization method used during training.

These two files are the core of the inference path. The app should be understood as:
raw text in -> vectorization -> model prediction -> spam/not-spam label out

##### C. Training and experimentation
**`Spam-detection.ipynb`**
- The notebook is the offline data science workspace used to explore the dataset, preprocess text, train the classifier, evaluate it, and export the final artifacts.
- It is not part of the deployed runtime, but it defines how `model.pkl` and `vectorizer.pkl` were produced.

##### D. Dataset
**`spam.csv`**
- Source dataset used for training and evaluation.
- This is the input to the notebook pipeline, not to the deployed app directly.

##### E. Dependency and environment support
**`requirements.txt`**
- Lists Python dependencies needed to run the notebook and/or Streamlit app.

**`nltk.txt`**
- Indicates NLTK resources or environment-specific NLP setup.
- This suggests text preprocessing depends on NLTK data or related NLP utilities.

**`side_image.json`**
- Likely a UI configuration or asset reference used by the Streamlit front end.
- It appears to support presentation rather than core ML logic.

#### 3) Data flow

The repository has two distinct data flows:

##### Offline training flow
1. `spam.csv` is loaded in `Spam-detection.ipynb`
2. Text preprocessing is applied
   - tokenization / normalization / stopword handling / stemming or lemmatization are likely involved based on the stated use of NLTK
3. Text is transformed into features using a vectorizer
4. A Naive Bayes model is trained on the labeled data
5. The trained model and vectorizer are serialized to:
   - `model.pkl`
   - `vectorizer.pkl`

This is the build-time pipeline that creates the deployable inference assets.

##### Online inference flow
1. User opens the Streamlit app through `app.py`
2. User enters an email/SMS message
3. The app preprocesses the message in the same way as training-time text preparation
4. The message is transformed using the persisted `vectorizer.pkl`
5. `model.pkl` generates a prediction
6. The UI renders the result as spam or not spam

#### 4) Architectural boundaries

##### Boundary 1: Training vs inference
This is the most important separation in the repo.

- **Training boundary:** notebook + dataset + experimentation
- **Inference boundary:** Streamlit app + serialized artifacts

This means the deployed app is not retraining in real time. It is a read-only consumer of previously generated ML assets.

##### Boundary 2: UI vs ML logic
The Streamlit layer is responsible for:
- collecting input
- displaying results
- handling page state and visuals

The ML layer is responsible for:
- feature extraction
- prediction

These are likely combined in one file for simplicity, but conceptually they are separate responsibilities.

##### Boundary 3: Static assets vs runtime logic
Screenshots, JSON UI-related data, and documentation are non-executable support files. They do not participate in classification, but they help define the presentation and documentation of the app.

#### 5) Technology stack and how it affects the architecture

##### Python
The whole project is Python-based, both for training and serving.

##### Streamlit
Streamlit is the runtime framework for the web interface.
Architecturally, this means:
- a lightweight server process
- immediate rendering of UI based on Python script execution
- no separate frontend/backend split

##### scikit-learn
Used for the classifier and vectorization workflow.
This indicates the model is a classic ML pipeline rather than a deep-learning system.

##### NLTK
Used for text preprocessing.
This is relevant because spam classification quality depends heavily on cleaning and normalizing text before vectorization.

##### pandas / numpy
Used in the notebook for data loading and preprocessing.

##### matplotlib / seaborn / wordcloud
Used for exploratory analysis and visualization in the notebook, not necessarily in the deployed app.

##### pickle
Used to persist the trained model and vectorizer to disk for later inference.

#### 6) Runtime deployment shape

The README mentions a deployed app hosted on Render. From an architectural perspective, that implies:

- the app is deployed as a single Streamlit service
- the service loads `model.pkl` and `vectorizer.pkl` at startup or on first use
- classification requests are handled in-process
- there is no dedicated backend microservice tier

This is a simple, monolithic deployment model that is appropriate for a lightweight classifier.

#### 7) What to show in an architecture diagram

If drawing the architecture, the main boxes should be:

- **User**
- **Streamlit App (`app.py`)**
- **Preprocessing / NLP layer**
- **Vectorizer (`vectorizer.pkl`)**
- **Naive Bayes model (`model.pkl`)**
- **Training notebook (`Spam-detection.ipynb`)**
- **Dataset (`spam.csv`)**

And the main arrows should be:

- User input -> Streamlit app
- Streamlit app -> preprocessing
- preprocessing -> vectorizer
- vectorizer -> model
- model -> classification result -> Streamlit UI

Separately, for the offline side:

- `spam.csv` -> notebook -> vectorizer/model artifacts

#### 8) Overall architectural summary

This repository implements a compact ML inference application with a clear separation between:

- **offline model development**
- **online interactive prediction**

The deployed experience is a Streamlit-based single service that loads serialized scikit-learn artifacts and classifies text messages in real time. The notebook and dataset exist to build those artifacts, while the app consumes them to provide the user-facing spam detection experience.

Main entry points: [`app.py`](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/app.py) (app.py), [`Spam-detection.ipynb`](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/Spam-detection.ipynb) (Notebook), [`vectorizer.pkl`](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/vectorizer.pkl) (Vectorizer), [`model.pkl`](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/model.pkl) (Naive Bayes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Online inference"
  user(("User<br/>actor"))
  app["app.py<br/>streamlit app<br/>[app.py]"]
  ui["Result UI<br/>presentation"]
  preprocess{{"Preprocess<br/>nlp step"}}
  vectorizer["Vectorizer<br/>artifact<br/>[vectorizer.pkl]"]
  model["Naive Bayes<br/>artifact<br/>[model.pkl]"]
end

subgraph "Offline training"
  notebook["Notebook"]
  data[("spam.csv<br/>dataset<br/>[spam.csv]")]
end

subgraph "Supporting assets"
  assets["Screenshots<br/>docs asset"]
  nltk["NLTK setup<br/>nlp support<br/>[nltk.txt]"]
  side["Side image<br/>ui asset<br/>[side_image.json]"]
end

user -->|"enter text"| app
app -->|"clean text"| preprocess
preprocess -->|"transform"| vectorizer
vectorizer -->|"features"| model
model -->|"result"| ui
notebook -->|"load"| data
data -->|"train on"| notebook
notebook -->|"uses"| nltk
notebook -->|"export"| vectorizer
notebook -->|"export"| model
app -->|"load"| vectorizer
app -->|"load"| model
app -.->|"show"| assets
app -.->|"read"| side

click app "https://github.com/gaurav241/email-sms-spam-classifier/blob/main/app.py"
click vectorizer "https://github.com/gaurav241/email-sms-spam-classifier/blob/main/vectorizer.pkl"
click model "https://github.com/gaurav241/email-sms-spam-classifier/blob/main/model.pkl"
click notebook "https://github.com/gaurav241/email-sms-spam-classifier/blob/main/Spam-detection.ipynb"
click data "https://github.com/gaurav241/email-sms-spam-classifier/blob/main/spam.csv"
click assets "https://github.com/gaurav241/email-sms-spam-classifier/tree/main/visuals/ss"
click nltk "https://github.com/gaurav241/email-sms-spam-classifier/blob/main/nltk.txt"
click side "https://github.com/gaurav241/email-sms-spam-classifier/blob/main/side_image.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class user,app,ui,preprocess,vectorizer,model toneBlue
class notebook,data toneAmber
class assets,nltk,side toneMint
```

## Components

### Online inference

Streamlit app that classifies user-entered messages at runtime.

- **User**: actor · Person entering a SMS or email message to classify.
- [app.py](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/app.py): streamlit app · Single-process Streamlit entry point for input, prediction, and result display. · `app.py`
- **Result UI**: presentation · Home, spam, and not-spam visual states rendered by the app.
- **Preprocess**: nlp step · Text normalization and cleanup before vectorization.
- [Vectorizer](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/vectorizer.pkl): artifact · Persisted feature extractor used to turn text into model inputs. · `vectorizer.pkl`
- [Naive Bayes](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/model.pkl): artifact · Persisted classifier that predicts spam or not spam. · `model.pkl`

### Offline training

Notebook-driven ML workflow that builds the serialized artifacts.

- [Notebook](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/Spam-detection.ipynb): training notebook · Offline experimentation and model-building workspace. · `Spam-detection.ipynb`
- [spam.csv](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/spam.csv): dataset · Labeled training corpus used to fit and evaluate the classifier. · `spam.csv`

### Supporting assets

Non-runtime assets used for presentation or environment setup.

- [Screenshots](https://github.com/gaurav241/email-sms-spam-classifier/tree/HEAD/visuals/ss): docs asset · UI screenshots used for README and visual documentation. · `visuals/ss`
- [NLTK setup](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/nltk.txt): nlp support · NLTK resource setup used by the text preprocessing pipeline. · `nltk.txt`
- [Side image](https://github.com/gaurav241/email-sms-spam-classifier/blob/HEAD/side_image.json): ui asset · Auxiliary UI-related JSON asset for the app presentation. · `side_image.json`

## Connections

- User → app.py: enter text · User submits a message to the Streamlit app.
- app.py → Preprocess: clean text · App prepares raw message text for feature extraction.
- Preprocess → Vectorizer: transform · Cleaned text is converted into numeric features using the persisted vectorizer.
- Vectorizer → Naive Bayes: features · Feature vectors are consumed by the classifier for prediction.
- Naive Bayes → Result UI: result · Predicted spam or not-spam label is rendered in the interface.
- Notebook → spam.csv: load · The notebook reads the training corpus for exploration and fitting.
- spam.csv → Notebook: train on · Labeled messages flow into the offline ML workflow.
- Notebook → NLTK setup: uses · Notebook relies on NLTK resources for text preprocessing.
- Notebook → Vectorizer: export · Training produces the serialized vectorizer artifact.
- Notebook → Naive Bayes: export · Training produces the serialized Naive Bayes model artifact.
- app.py → Vectorizer: load · Runtime app loads the persisted vectorizer for inference.
- app.py → Naive Bayes: load · Runtime app loads the persisted model for inference.
- app.py → Screenshots: show · Screenshots support the documented UI states.
- app.py → Side image: read · App may use auxiliary UI configuration or asset data.
