AI-assisted misinformation detection with live web evidence, transparent verdicts and an editorial-dispatch interface.
Live demo Β· What it does Β· Screenshots Β· How it works Β· Design Β· Quick start Β· Project structure Β· Security Β· API Β· Testing Β· Deployment Β· Roadmap
debunk-it.vercel.app: No sign-up required to scan a claim, headline or article URL. Create a free account to maintain a searchable investigation ledger and telemetry dossier.
- Primary Domain: https://debunk-it.vercel.app
- Legacy Disambiguation Route: https://debunkit-pi.vercel.app (automatically 307-redirects to primary)
- Hosting: Vercel Global Edge Network with Python serverless execution and instant edge CDN asset delivery.
Misinformation spreads faster than fact-checking can keep up. DEBUNK.IT gives anyone a quick, evidence-backed read on a headline, an article URL or a block of full text, and shows its reasoning instead of just a score.
| Capability | Implementation |
|---|---|
| π§ Hybrid AI pipeline | Cohere command-r reasoning, a trained TF-IDF + Logistic Regression model (93% accuracy on WELFake) and a local NLP engine for instant offline fallbacks |
| π Live web evidence (RAG) | Multi-query DuckDuckGo live search with automated fact-check source corroboration |
| π URL scraper | Pulls the article body and uses it as primary evidence with SSRF protection |
| π§Ύ Transparent verdicts | Stamp badge, confidence meter, written reasoning, cited sources and red flags |
| π History and telemetry | Searchable ledger of past scans plus verdict, confidence and engine-mode breakdowns |
| π Export | Copy a verification dossier or download a receipt as .txt |
| π¬ Community reviews | Visitors can read and submit peer reviews on the dispatch desk |
| π‘οΈ Security first | CSRF protection, SSRF DNS blocking, XSS sanitisation, rate limiting, hashed passwords |
| π Light and dark themes | Newsprint paper by day (#F4F1EA), warm charcoal by night (#141413) |
| Verdict | Meaning |
|---|---|
β
SUPPORTED |
Credible evidence confirms the central claim |
β REFUTED |
Credible sources contradict the claim |
MISLEADING |
Partly true, but missing context, old media or misrepresented |
π INSUFFICIENT EVIDENCE |
Sources neither clearly confirm nor deny |
π© LOW CREDIBILITY |
Suspicious language or weak sourcing, but not directly refutable |
flowchart TD
A["Headline, URL or text"] --> B["Input validation<br/>length limits, SSRF guard, sanitising"]
B -- "URL mode" --> C["Article scraper"]
B -- "Headline or text" --> D["Live web search (RAG)"]
C --> D
D --> E["Cohere reasoning<br/>with source-aware prompts"]
E -- "AI unavailable" --> F["Local ML + NLP fallback"]
E --> G["Verdict + confidence + receipts"]
F --> G
G --> H[("Database<br/>history and cache")]
classDef ink fill:#1B1B1B,stroke:#1B1B1B,color:#E4E0D3;
classDef red fill:#C8423B,stroke:#1B1B1B,color:#fff;
classDef paper fill:#E4E0D3,stroke:#1B1B1B,color:#1B1B1B;
class A,G ink;
class B red;
class C,D,E,F,H paper;
Results are cached per user (6 hours for URLs, 24 hours for text) so repeat checks are instant.
git clone https://github.com/Soul-Ninja/Debunkit.git
cd Debunkit
python -m venv .venv
.venv\Scripts\activate # macOS/Linux: source .venv/bin/activate
pip install -r requirements.txtCreate a .env file in the project root:
COHERE_API_KEY=your_cohere_api_key
SECRET_KEY=a_long_random_string
DATABASE_URL=sqlite:///debunkit.db
FLASK_ENV=developmentA free Cohere API key is available at cohere.com. Without one, DEBUNK.IT falls back gracefully to the local ML and NLP engines.
python debunkit_app.pyflask db migrate -m "description" # create a migration from model changes
flask db upgrade # apply pending migrations to databaseOpen http://127.0.0.1:5000.
Debunkit/
βββ api/
β βββ index.py Vercel serverless WSGI adapter & path-fix middleware
βββ vercel.json Vercel deployment & rewrite configuration
βββ public/ Static assets optimized for Vercel Edge CDN
β βββ static/ CSS, JS, and Image mirrors for 0ms static delivery
βββ debunkit_app.py Core Flask application: views, routes and APIs
βββ config.py Development / Production / Testing configurations
βββ serve.py Waitress production server wrapper
βββ Dockerfile Container image (Gunicorn)
β
βββ Core/
β βββ ai_engine.py Cohere reasoning & hybrid analysis pipeline
β βββ rag_engine.py Live search & article scraper
β βββ nlp_engine.py Offline heuristic & pattern engine
β βββ database.py SQLAlchemy database models
β βββ user_model.py Authentication model (Flask-Login)
β
βββ utils/ validators.py (SSRF guard) Β· sanitizer.py (XSS prevention)
βββ Template/ landing Β· index (scanner, ledger, telemetry) Β· auth Β· profile Β· settings
βββ Static/ CSS Β· JS (landing, main, canvas) Β· Images
βββ tests/ Comprehensive pytest suite (86 tests)
βββ docs/screenshots/ README visual documentation
| Layer | Tools |
|---|---|
| Hosting & Edge | Vercel Serverless Functions (Python 3.12), Vercel Global Edge CDN |
| Backend | Flask 3.x, Flask-Login, Flask-Limiter, Flask-SQLAlchemy, Flask-CORS, Werkzeug |
| AI / ML | Cohere command-r-08-2024, scikit-learn (TF-IDF + Logistic Regression), DuckDuckGo search (ddgs), BeautifulSoup4 |
| Frontend | Jinja2 templates, vanilla JavaScript (ES6+), CSS custom properties, HTML5 canvas. No external UI frameworks |
| Data | SQLite for local/ephemeral runs, PostgreSQL via DATABASE_URL for persistent production |
| Security | CSRF tokens, SSRF IP-resolver guards, HTML sanitization, secure cookies, rate limiting |
| Layer | Protection |
|---|---|
validators.py |
Length limits, null-byte stripping, URL scheme enforcement, SSRF blocking via DNS resolution |
sanitizer.py |
XSS prevention: HTML escaping, script removal, javascript: / data: blocking |
debunkit_app.py |
CSRF token required on every POST, PUT, PATCH and DELETE |
main.js |
Sends X-CSRFToken; refuses non-HTTP source URLs in the DOM |
config.py |
Rate limiting, password complexity rule, secure session cookies |
| Method | Endpoint | Description |
|---|---|---|
POST |
/analyze |
Run claim or article verification |
GET |
/api/history |
Signed-in user's analysis history |
GET |
/api/analysis/<id> |
Full analysis receipt with sources |
GET |
/api/search?q= |
Search past analyses |
GET |
/api/stats |
Global verdict and claim statistics |
POST |
/api/clear-database |
Delete user analysis records |
GET PUT |
/api/user/profile |
View or update profile |
PUT |
/api/user/settings |
Theme, password and preferences |
DELETE |
/api/user/delete |
Delete account and user data |
GET POST |
/api/reviews |
Read or submit editorial reviews |
GET |
/api/health |
Service health status |
GET |
/api/ready |
Database readiness status |
pip install -r requirements-dev.txt
pytest -q86 unit and integration tests cover:
- API responses, headers, and HTTP status codes
- Cohere AI engine integration & offline ML fallbacks
- SSRF validation (blocking localhost, private subnets, cloud metadata IPs)
- XSS sanitisation and payload filtering
- Authentication, CSRF token handling, and password complexity enforcement
Local ML baseline: On 1,000 held-out samples from WELFake, the TF-IDF + Logistic Regression fallback scores ~93% accuracy at roughly 1.6 ms per query (see debunkit_metrics_summary.md).
The live application runs serverless on Vercel with global Edge CDN asset caching:
- Connect the repository to Vercel with the Flask application preset.
- Environment variables needed in Vercel Project Settings:
SECRET_KEY: A secure random cryptographic stringCOHERE_API_KEY: Your Cohere API keyFLASK_ENV:production
- Automatic zero-downtime deployment triggers on every git push to
main.
docker build -t debunkit .
docker run -p 8080:8080 --env-file .env debunkitgunicorn -w 4 -b 0.0.0.0:5000 debunkit_app:app- Not a final authority. DEBUNK.IT is an assistant, not a replacement for human judgment.
- Breaking news, satire, AI-generated images and conflicting sources may still need manual checking.
- The local ML model detects writing patterns, not factual truth.
- Full AI analysis needs a Cohere API key; without one it falls back to local pattern analysis.
- Search quality depends on DuckDuckGo availability and can drop for very recent events.
- Hybrid analysis pipeline (AI + ML + NLP)
- Accounts, history and telemetry
- Security hardening (CSRF, SSRF, XSS, rate limiting)
- Docker support and CI
- Editorial redesign with light and dark themes
- Signature motion layer
- Vercel serverless deployment & custom domain (
debunk-it.vercel.app) - Browser extension
- Image and video misinformation detection
- Multilingual support
- Public API with keys
- Fork the repository
- Create a branch:
git checkout -b feature/your-feature - Commit:
git commit -m "feat: your feature" - Push and open a Pull Request
MIT License Β· Built by Soul-Ninja
Analyze claims before they spread.
β Star the repo if it helped you






