Full-Stack Spam Detection System (CNN + React + FastAPI)

A complete web application for detecting spam messages in real time. This prediction engine is powered by a Convolutional Neural Network (CNN).

---

What This Project Does

This app combines a trained deep learning model with a modern web stack:

• A CNN classifier (Keras) trained to recognize spam vs. ham text patterns
• A FastAPI backend serving predictions over a REST API
• A React + Vite frontend for submitting messages and visualizing results

Users can submit a message and instantly get a spam/ham classification along with a confidence score along with a dashboard of live statistics.

---

Core Features

Machine Learning

• Keras CNN model trained for text classification
• Confidence-scored predictions returned per request
• Model can be reloaded on the fly (no server restart needed)

Backend — FastAPI

• REST endpoints for prediction, stats, health checks, and model reload
• Auto-generated API docs via Swagger (/docs)
• CORS configured for frontend integration
• Structured logging and typed response models

Frontend — React + Vite

• Clean, responsive UI with light/dark theme toggle
• Live results view after each submitted message
• Analytics dashboard with:
  • Radar chart — Accuracy / Precision / Recall / F1
  • Timeline chart — confidence over recent predictions
  • Pie chart — spam vs. ham ratio
  • Bar chart — confidence distribution
• History panel of the last 20 predictions
• Summary stat cards for key metrics

---

API Reference

Method	Route	Purpose
POST	/predict	Classify a single message
GET	/statistics	Get model metrics + recent prediction stats
DELETE	/history	Wipe stored prediction history
PUT	/model/reload	Hot-reload the CNN model
GET	/health	API/model health check

---

Tech Stack

Backend: FastAPI, TensorFlow/Keras, Uvicorn, NumPy, Pydantic

Frontend: React 19, Vite, Axios, Chart.js, react-chartjs-2, Tailwind CSS, Lucide React

---

Getting Started

Requirements

• Python 3.11+
• Node.js 20+
• npm or yarn

1. Backend Setup

Windows (venv):

cd Spam-Detection-Project/backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

If TensorFlow fails to install, enable Windows long paths. See this guide.

macOS (venv):

cd Spam-Detection-Project/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Conda (any OS):

conda create -n spamdetect python=3.11
conda activate spamdetect
pip install -r requirements.txt

2. Frontend Setup

cd Spam-Detection-Project/frontend
npm install

3. Run It

Open two terminals:

Terminal 1 — Backend

cd Spam-Detection-Project/backend
python -m uvicorn app.main:app --reload

• API: http://127.0.0.1:8000
• Docs: http://127.0.0.1:8000/docs

Terminal 2 — Frontend

cd Spam-Detection-Project/frontend
npm run dev

• App: http://localhost:5173

---

Project Layout

Spam-Detection-Project/
├── backend/
│   ├── app/
│   │   ├── core/
│   │   │   ├── model_loader.py
│   │   │   ├── predictor.py
│   │   │   ├── preprocessor.py
│   │   │   └── state.py
│   │   ├── routes/
│   │   │   ├── predict_routes.py
│   │   │   ├── management_routes.py
│   │   │   └── health_routes.py
│   │   ├── schemas/
│   │   │   ├── request_models.py
│   │   │   └── response_models.py
│   │   ├── utils/
│   │   │   ├── helpers.py
│   │   │   └── logger.py
│   │   └── main.py
│   ├── models/
│   │   ├── cnn_spam_model.keras
│   │   └── cnn_tokenizer.pkl
│   └── requirements.txt
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Charts/
│   │   │   │   ├── ConfidenceChart.jsx
│   │   │   │   ├── DistributionChart.jsx
│   │   │   │   ├── PerformanceChart.jsx
│   │   │   │   └── TimelineChart.jsx
│   │   │   ├── NavBar.jsx
│   │   │   ├── Footer.jsx
│   │   │   ├── PredictionForm.jsx
│   │   │   ├── PredictionResult.jsx
│   │   │   ├── StatsCards.jsx
│   │   │   └── HistoryPanel.jsx
│   │   ├── services/
│   │   │   └── api.js
│   │   ├── utils/
│   │   │   └── exportUtils.js
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js
│
├── README.md
└── architecture.md

---

Using the App

1. Launch the frontend in your browser
2. Paste or type a message into the input box
3. Click Analyze Message
4. View the spam/ham verdict and confidence score

---

About the Model

CNN Architecture:

• Tokenized/padded input sequences (max length: 100)
• Embedding layer for semantic representation
• Conv + pooling layers for pattern extraction
• Dense layers with sigmoid output
• Binary output (spam/ham) with confidence value

Preprocessing pipeline:

1. Clean and normalize raw text
2. Tokenize using the pre-trained tokenizer
3. Pad sequences to a fixed length (100)
4. Convert to NumPy arrays for inference

Metrics tracked:

Metric	Meaning
Accuracy	Overall correctness
Precision	Correctness of spam predictions
Recall	Ability to catch actual spam
F1-Score	Harmonic mean of precision & recall

These are surfaced live on the dashboard and via /statistics.

---

Dashboard & Visualization

Built with Chart.js:

• Radar chart for model performance metrics
• Line chart with zoom/filter for confidence trends over time
• Pie chart for spam/ham distribution
• Bar chart for confidence-range distribution
• CSV export for all charts
• Full dark mode support
• Responsive across screen sizes

Theme preference (light/dark) persists between sessions.

Model management tools:

• Reload the model without restarting the server
• Clear prediction history
• Check system health via /health

---

Performance Snapshot

Task	Time
Single prediction	20–50 ms
Model load	~3s
Frontend initial load	<1s

---

Troubleshooting

Backend

• Model won't load → confirm .keras and .pkl files are present in models/
• Port already in use → change the Uvicorn port
• Import errors → verify Python package versions match requirements.txt

Frontend

• Can't reach API → make sure the backend is running on port 8000
• Charts not rendering → check the browser console for errors
• Dark mode acting up → clear browser cache

---

Summary

A full-stack spam detection system combining a CNN classifier with a real-time web interface. This is built for message-level classification, live analytics, and a responsive UI suited to both end users and researchers.