An end-to-end Machine Learning pipeline and web application designed to detect spam messages.
Spam Message Collector is a full-stack, end-to-end machine learning system engineered to classify text messages as either spam or safe (ham). It demonstrates a modern, scalable approach to deploying machine learning models, isolating the data pipeline, inference API, and user interface into distinct, manageable components.
The project lifecycle is built on a robust, modular architecture:
- Data Collection & Management: Raw dataset acquisition via automated scripts, securely stored locally. Data is processed and versioned across separate raw and processed data stores.
- NLP Pipeline: Comprehensive text preprocessing utilizing Python and NLTK. This includes lowercasing, punctuation removal, tokenization, stop-word elimination, and lemmatization, followed by TF-IDF vectorization.
- Model Training: Training robust machine learning classifiers (e.g., Naive Bayes, SVM) on the processed corpus. The best-performing model is serialized for decoupled deployment.
- Backend (Inference API): A high-performance FastAPI application. It loads the serialized model on startup (utilizing the Singleton pattern for efficiency) and exposes asynchronous POST endpoints for real-time inference.
- Frontend (Client): A dynamic React.js user interface, allowing users to intuitively input text and visualize the classification results instantly.
- Core / Data Science: Python, NLTK, Scikit-Learn, Pandas, NumPy
- Backend: FastAPI, Uvicorn, Pydantic
- Frontend: React.js, Vite, Axios, Oxlint
- CI/CD & DevOps: GitHub Actions, Pytest, Ruff
spam-message-collector/
├── .github/
│ └── workflows/
│ ├── ci.yml # Main CI: Python Matrix (3.10-3.12), Pytest, Ruff, Oxlint, Vite Build
│ └── security.yml # Security and dependency audit workflow
├── backend/ # FastAPI REST API
├── data/ # Datasets (raw & processed)
├── frontend/ # React + Vite Client
├── models/ # ML training scripts and serialized artifacts
├── preprocessing/ # NLP TextCleaner pipeline
├── tests/ # Pytest unit & API integration test suite
├── pyproject.toml # Pytest and Ruff configuration
├── requirements.txt # Python dependencies
└── README.md
The project features a Senior-grade automated CI/CD pipeline powered by GitHub Actions with fail-fast execution, dependency caching, and full coverage.
# Activate virtual environment
source .venv/bin/activate
# Run full Pytest suite
pytest -v# Python linting and formatting check
ruff check .
ruff format --check .
# Frontend static analysis and production build check
cd frontend
npm run lint
npm run buildOn every push and pull_request to main, GitHub Actions automatically:
- 🐍 Python Quality Gate: Runs
ruff checkandruff formatto enforce clean code. - 🧪 Matrix Testing: Executes 20+ unit and API integration tests across Python
3.10,3.11, and3.12. - ⚛️ Frontend Linter: Performs static analysis with
oxlint. - 📦 Production Build: Validates that the React/Vite SPA builds successfully without errors.
- ⚡ Smart Caching: Utilizes
pipandnpmcache to maintain pipeline speeds under 30 seconds.
- Implement advanced Deep Learning models (e.g., LSTM, BERT).
- Add extensive unit and integration tests (20+ automated tests).
- Dockerization: Containerize the React frontend and FastAPI backend using Docker and
docker-composefor seamless, independent scaling and deployment. - Implement CI/CD pipelines with GitHub Actions.
Follow these steps to set up the project locally from scratch.
- Python 3.10+ (python.org)
- Node.js v18+ and npm (nodejs.org)
- Git (git-scm.com)
-
Clone the repository:
git clone https://github.com/Semi-2005/spam-message-collector.git cd spam-message-collector -
Create and activate a Python virtual environment:
python3 -m venv .venv source .venv/bin/activate # macOS / Linux # .venv\Scripts\activate # Windows
-
Install backend (Python) dependencies:
pip install --upgrade pip pip install -r requirements.txt
Not: NLTK veri dosyaları (stopwords, wordnet, punkt) ilk çalıştırmada otomatik indirilir. İnternet bağlantısı gereklidir.
-
Download the dataset:
python download_dataset.py
-
Train the ML model:
python -m models.train_model
Bu adım
models/artifacts/altına eğitilmiş model (best_model_pipeline.joblib) ve metadata dosyasını oluşturur. Eğitim ~30 saniye sürer. -
Install frontend (Node.js) dependencies:
cd frontend npm install cd ..
The application requires two terminals — one for the backend API and one for the frontend React app.
Terminal 1 — Backend (FastAPI):
cd spam-message-collector
source .venv/bin/activate
uvicorn backend.main:app --reload --port 8000The API will be available at
http://127.0.0.1:8000. Swagger docs:http://127.0.0.1:8000/docs
Terminal 2 — Frontend (React):
cd spam-message-collector/frontend
npm run devFrontend
http://localhost:5173adresinde açılacaktır.
Tarayıcıda http://localhost:5173 adresini açarak uygulamayı kullanabilirsiniz.
You can also test the classification endpoint directly using curl:
curl -X POST "http://127.0.0.1:8000/api/v1/classify" \
-H "Content-Type: application/json" \
-d '{"text": "Congratulations! You have won a $1,000 Walmart gift card. Click here to claim your prize."}'Expected Response:
{
"text": "Congratulations! You have won a $1,000 Walmart gift card. Click here to claim your prize.",
"label": "spam",
"is_spam": true,
"spam_probability": 0.671,
"confidence_level": "Orta"
}- Implement advanced Deep Learning models (e.g., LSTM, BERT).
- Add extensive unit and integration tests.
- Dockerization: Containerize the React frontend and FastAPI backend using Docker and
docker-composefor seamless, independent scaling and deployment. - Implement CI/CD pipelines with GitHub Actions.
Distributed under the MIT License. See LICENSE for more information.