Chatfilter

AI-powered chat spam and scam detector with explainable risk scoring.

Overview

Detects spam, scam, and safe chat messages. Supports single and batch message analysis. Shows spam probability, risk level, top model terms, and rule-based hints. Maintains analysis history with delete support. Exposes REST API endpoints for integration.

Core Architecture

flowchart LR
    User -->|submits messages| Frontend["React SPA (Vite + TypeScript)"]
    Frontend -->|REST API| Backend["FastAPI Backend"]
    Backend -->|validates| Schemas["Pydantic Schemas"]
    Backend -->|detects| ML["TF-IDF + LogisticRegression"]
    Backend -->|rules| Heuristics["Rule-based Scam Hints"]
    Backend -->|stores| DB[(SQLite)]
    Backend -->|metrics| Metrics["Model Metrics Artifacts"]

Loading

System Components

Component	Responsibility
backend/app/	FastAPI application, routes, schemas
backend/app/ml/	Model training, inference, metrics
backend/tests/	Backend test suite (pytest)
frontend/src/	React components and UI
frontend/tests/	Frontend test suite (Vitest)

Repository Layout

Directory	Purpose
backend/	FastAPI REST API server
frontend/	React + Vite client
backend/app/ml/	ML training and inference

Technology Stack

Layer	Technology	Purpose
Frontend	React + TypeScript + Vite	Chat interface
Styling	Tailwind CSS	UI styling
Backend	FastAPI + Python	REST API
ORM	SQLAlchemy	Database access
Database	SQLite	Message storage and history
ML	scikit-learn	TF-IDF + Logistic Regression
Testing	pytest + Vitest	Backend and frontend tests
Serialization	joblib	Model persistence

Requirements

• Python 3.10+
• Node.js 18+
• npm
• uv (Python package manager)

Getting Started

# Backend
cd backend
python -m venv ../.venv
../.venv/bin/python -m pip install -r requirements.txt
PYTHONPATH=. ../.venv/bin/python -m uvicorn app.main:app --reload

# Frontend
cd frontend
npm install
npm run dev

Development

# Backend tests
PYTHONPATH=backend .venv/bin/python -m pytest backend/tests -q

# Frontend tests
npm --prefix frontend test -- --run
npm --prefix frontend run build

# Train model
cd backend
PYTHONPATH=. ../.venv/bin/python -m app.ml.train \
  --data data/seed_messages.csv \
  --model artifacts/spam_model.joblib \
  --metrics artifacts/model_metrics.json