How gaurav241/email-sms-spam-classifier works
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 app.py · Spam-detection.ipynb Notebook · vectorizer.pkl Vectorizer · model.pkl Naive Bayes
Components 11
Online inference
Streamlit app that classifies user-entered messages at runtime.
- User · Person entering a SMS or email message to classify.
- app.py · Single-process Streamlit entry point for input, prediction, and result display.
app.py - Result UI · Home, spam, and not-spam visual states rendered by the app.
- Preprocess · Text normalization and cleanup before vectorization.
- Vectorizer · Persisted feature extractor used to turn text into model inputs.
vectorizer.pkl - Naive Bayes · Persisted classifier that predicts spam or not spam.
model.pkl
Offline training
Notebook-driven ML workflow that builds the serialized artifacts.
Supporting assets
Non-runtime assets used for presentation or environment setup.
- Screenshots · UI screenshots used for README and visual documentation.
visuals/ss - NLTK setup · NLTK resource setup used by the text preprocessing pipeline.
nltk.txt - Side image · Auxiliary UI-related JSON asset for the app presentation.
side_image.json
Connections 14
- 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.