TraceOrigin — the phishing-aware job & opportunity verification platform. Paste a WhatsApp message, email, or job offer and get an explainable, evidence-backed risk score in seconds.
Paste any offer → get an explainable risk verdict in seconds — payment demands, urgency traps, phony deadlines and personal-email red flags, all surfaced instantly.
- What is TraceOrigin?
- Why it exists
- Key Features
- Screenshots
- Tech Stack
- Architecture
- Getting Started
- Configuration
- API Reference
- Project Structure
- Performance & Engineering Notes
- Releases & Packages
- Roadmap
- Contributing
- License
- Disclaimer
TraceOrigin is a full-stack student opportunity verification platform. Every day students receive internship offers, "urgent" WhatsApp jobs, and prize "winners" messages — many engineered to steal money or personal data. TraceOrigin turns any raw opportunity text into a clear, explainable verification trail:
- an explainable 0–100 risk score with a live gauge,
- warning indicators per detected scam pattern (payment demands, urgency, personal emails, no-interview hiring),
- a verification checklist and a machine-readable recommendation,
- a personalized dashboard with trends and risk distribution,
- a global Scam Intelligence Center aggregating patterns across all users.
Screenshot OCR is built in (Tesseract.js) — upload a screenshot of the offer and the text is extracted for free.
"Congratulations! You have been selected… Pay ₹1999 registration fee today. Only 10 seats remaining."
This exact message is sent to thousands of students every day. Scammers exploit urgency, fake scarcity, and personal contact channels (WhatsApp, Telegram, Gmail, Paytm / UPI / Google Pay).
TraceOrigin answers one question a student should always ask: is this opportunity — or this origin — worth trusting? It is deliberately not a black-box verdict. Every score ships with the evidence trail behind it, so the user stays the decision-maker.
Verification engine (backend)
- ✅ Rule-based risk engine with 30+ detection signals across payment, urgency, contact-channel, and legitimacy patterns
- ✅ Explainable scores —
CRITICAL / HIGH / MEDIUM / LOWplus a written recommendation - ✅ Structured information extraction (company, role, salary, location, contact, source, website) from free text
- ✅ JWT authentication (salted-SHA-256 password hashing, HS256 tokens) with per-user data scoping
- ✅ Full REST API — analyze, history, search/filter, delete, dashboard stats, global intelligence
Experience (frontend)
- 🚀 Code-split lazy routes — 1.15 MB monolithic bundle split into a ~15 KB initial payload
- 📊 Recharts analytics — 7-day trends, risk-distribution pie, weekly activity, warning-signal bars
- 🖼️ Screenshot OCR with live progress (Tesseract.js, lazy-loaded)
- 📑 One-click report export — PDF, copy-to-clipboard, share, e-mail, and print-clean (A4 stylesheet)
- 🎛️ AuthKit-inspired frosted-glass design system: violet
#663af3canvas, glass surfaces, pill buttons, micro-interactions - 🧭 Role-appropriate navigation, protected routes, mobile-first responsive layout
- 🔔 Notification preferences, profile management, and secure session handling
The app is fully designed in a frosted-glass, midnight "cathedral" visual language. Here is the complete flow — from the landing page through signing in to the analytics dashboards.
Click any thumbnail to open the full-size screenshot.
 |
 |
 |
 |
 |
 |
|
 |
 |
 |
 |
 |
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React 18 + Vite 5 | UI runtime & build tooling |
| Tailwind CSS 3 | The AuthKit-inspired design system (tokens, glass, animations) | |
| Recharts | Dashboard & analytics visualizations | |
| Tesseract.js 7 | Client-side screenshot OCR (lazy-loaded) | |
| jsPDF + jspdf-autotable | One-click PDF report export | |
| Lucide React | Icon system | |
| Backend | Python 3.12 + FastAPI | REST API, OAuth2-style JWT auth |
| SQLAlchemy 2 + PyMySQL | ORM & MySQL driver | |
| python-jose | HS256 JWT signing | |
| Pydantic 2 | Request/response validation | |
| Database | MySQL 8 | Users, analyses, alerts |
| Infra | GitHub Actions | CI (build + verify) and automated releases |
┌────────────────────┐ ┌─────────────────────┐ ┌──────────────────────┐
│ React 18 + Vite │ HTTP │ FastAPI │ SQL │ MySQL 8 │
│ (SPA, lazy routes)│ ─────► │ /api/* routers │ ─────► │ users / analyses / │
│ frosted-glass UI │ JWT │ Rule-Based Engine │ │ alerts │
└────────────────────┘ └─────────────────────┘ └──────────────────────┘
├─ Information extractor
├─ Indicator generator (30+ signals)
└─ Risk scorer + recommendation engine
- Frontend ships as a static bundle (Vite build) and talks only to
/api/*through the dev proxy or your CORS-allowed origin. - Backend is a thin FastAPI layer. Business logic lives in
backend/app/analyzer.py(risk engine),extractor.py(entity extraction), andadvanced_analyzer.py(deep patterns). - Auth uses
OAuth2PasswordBearer+ HS256 JWTs; passwords are salted-SHA-256 hashes. - Every request is scoped to the authenticated user — history, dashboard stats, and deletes never cross account boundaries (verified by an owner check in the history route).
| Tool | Version | Notes |
|---|---|---|
| Python | 3.10+ | 3.12 recommended (pinned deps wheel-tested) |
| Node.js | 18+ | 20/22 LTS recommended |
| MySQL | 8.x | Create the traceorigin database yourself |
| Git | — | For cloning |
CREATE DATABASE IF NOT EXISTS traceorigin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;Tables are auto-created on first boot by Base.metadata.create_all — no migrations to run.
cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -r requirements.txtCreate your environment file:
cp .env.example .envENV=development
DATABASE_URL=mysql+pymysql://root:yourpassword@localhost:3306/traceorigin
SECRET_KEY=replace-with-a-long-random-secret
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30Run the API:
uvicorn app.main:app --reload --port 8001Health check → http://localhost:8001/api/health → {"status":"healthy","service":"TraceOrigin API"}
cd frontend
npm install
npm run devOpen http://localhost:5173 — the Vite dev server proxies /api to http://localhost:8001.
| Command | What it does |
|---|---|
npm run dev (frontend) |
Dev server on :5173 with /api proxy |
npm run build |
Production build → frontend/dist/ |
npm run preview (frontend) |
Serve the production build locally |
uvicorn app.main:app --reload --port 8001 (backend) |
Dev API on :8001 |
Prefer one-command helpers? The scripts/ folder has cross-platform start scripts:
# Windows PowerShell
.\scripts\start-backend.ps1
.\scripts\start-frontend.ps1
# macOS / Linux
./scripts/start-backend.sh
./scripts/start-frontend.shSeeded for trying the product end-to-end (includes 8 analyses across all risk levels + a 7-day trend):
Email: demo@traceorigin.app
Password: Demo@1234
⚠️ The demo dataset lives in your local MySQL from the seed script. While it exists, anyone can sign in with these credentials on your local instance.
| Variable | Default | Description |
|---|---|---|
ENV |
development |
Runtime environment flag |
DATABASE_URL |
mysql+pymysql://… |
SQLAlchemy connection string |
SECRET_KEY |
(change me) | JWT signing secret — always override in production |
ALGORITHM |
HS256 |
JWT signing algorithm |
ACCESS_TOKEN_EXPIRE_MINUTES |
30 |
Access-token lifetime |
| Variable | Default | Description |
|---|---|---|
VITE_API_BASE_URL |
/api |
Override for CORS/remote deployments |
Base URL: http://localhost:8001/api
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET |
/health |
— | Health check |
POST |
/auth/register |
— | Create account {email, username, password, full_name} |
POST |
/auth/login |
— | OAuth2 form login → {access_token} |
GET |
/auth/me |
✅ | Current user profile |
POST |
/analyze |
✅ | Analyze opportunity text {text} → full report |
GET |
/history |
✅ | List analyses ?search=&risk_filter= |
GET |
/history/{id} |
✅ | Full report for one analysis (owner-scoped) |
DELETE |
/history/{id} |
✅ | Delete one analysis (owner-scoped) |
GET |
/dashboard/stats |
✅ | Totals, risk distribution, 7-day trends, signals, recent |
GET |
/dashboard/intelligence |
✅ | Global intelligence snapshot |
GET |
/intelligence/scam-patterns |
✅ | Pattern frequency across all analyses |
GET |
/intelligence/company-risk?company= |
✅ | Aggregate risk for a company name |
Analyze response shape
TraceOrigin/
├─ backend/
│ ├─ app/ # FastAPI application
│ │ ├─ routes/ # analyze · auth · dashboard · health · history · intelligence · alerts
│ │ ├─ analyzer.py # Rule-based risk engine (30+ signals)
│ │ ├─ advanced_analyzer.py # Deep pattern detection
│ │ ├─ extractor.py # Company / role / salary / entity extraction
│ │ ├─ auth.py # JWT helpers + current-user dependency
│ │ ├─ config.py # Env-driven settings
│ │ ├─ database.py # SQLAlchemy engine + session
│ │ ├─ main.py # App factory, CORS, router wiring
│ │ ├─ models.py # User · Analysis · (alerts)
│ │ └─ schemas.py # Pydantic models
│ ├─ .env.example
│ ├─ requirements.txt
│ └─ runtime.txt
├─ frontend/
│ ├─ src/
│ │ ├─ api/client.js # Axios client + typed wrappers (JWT interceptor)
│ │ ├─ components/ # Analyzer · Dashboard · History · Landing · Navbar · Results · RiskGauge · ScamIntelligence · …
│ │ ├─ context/AuthContext.jsx # Session state + login/logout
│ │ ├─ App.jsx # Lazy route table + Suspense
│ │ ├─ index.css # Design-system tokens & component classes
│ │ └─ main.jsx
│ ├─ index.html
│ ├─ package.json
│ ├─ tailwind.config.js
│ └─ vite.config.js # Dev proxy + vendor chunk splitting
├─ docs/
│ ├─ logo.svg / logo-horizontal.svg / logo.png
│ └─ screenshots/ # 12 marketing screenshots
├─ scripts/ # Cross-platform start helpers
├─ .github/workflows/ # CI + release automation
├─ .gitignore
├─ LICENSE # MIT
└─ README.md
- Initial bundle ≈ 15 KB (gzip ~6.5 KB). The original single 1.15 MB entry chunk was split into route-level lazy chunks — recharts, jsPDF, and Tesseract now load only on the pages that need them.
- Vendor caching —
react,react-dom,react-router-dom, andlucide-reactland in cacheable, immutable vendor chunks. - Dashboard uses the server endpoint (
/dashboard/stats) instead of shipping full history to the browser for client-side aggregation — less bandwidth, one round trip. - Smooth interactions — global press micro-scaling (
active:scale), 150–300 ms transitions, a fade-up page transition keyed by route, and-webkit-tap-highlight-colorremoval for mobile. - OCR is race-safe — a run-id guard ignores stale async results if the user cancels mid-extraction; failures degrade gracefully to manual paste.
- Backend indexes —
analyses.created_atindexed for the 7-day trend queries;user_idis FK-indexed by MySQL.
- GitHub Releases — see
RELEASE.mdfor the release checklist and how versions are cut. - GitHub Packages — every tag published to
npmships the frontend as a public npm package on the GitHub Packages registry:@sabynextdoor/traceorigin-frontend— see the repo's Packages tab. - Automated packaging — the
release.ymlworkflow, on everyv*tag:- 📦 publishes
@sabynextdoor/traceorigin-frontendto GitHub Packages (npm publish) - 📦 attaches the production build as
traceorigin-frontend.tar.gz - 📦 attaches the npm tarball via
npm pack
- 📦 publishes
- Source archives — every release automatically includes GitHub's generated
.zip/.tar.gz. - Versioning follows SemVer (
v1.0.0,v1.1.0, …).
Install the published frontend package (from any project):
npm config set @sabynextdoor:registry https://npm.pkg.github.com
npm install @sabynextdoor/traceorigin-frontend(Access requires auth for GitHub Packages when not using a GitHub Actions token — see GitHub docs.)
Manual release (if you prefer not to use the workflow):
- Deep-learning risk scoring (beyond rule-based signals)
- Email & WhatsApp sharing with a public/private share link
- MFA + refresh-token rotation for production auth
- Company/domain verification API (WHOIS, MX, reputation)
- CSV export of history for personal audit trails
- Realtime alerting on newly reported scam patterns (Dockerized alert worker)
- Fork the repository.
- Create a feature branch (
git checkout -b feat/my-feature). - Commit your changes (
git commit -m "feat: …"). - Push to the branch (
git push origin feat/my-feature). - Open a Pull Request.
Quality bar: frontend must pass npm run build; backend must boot with uvicorn app.main:app. Route changes must stay user-scoped. Secrets never enter the repo.
Distributed under the MIT License. See LICENSE for details.
TraceOrigin provides risk indicators based on available information. A high score does not prove fraud, and a low score does not guarantee legitimacy. Always verify opportunities through official channels before sharing money or personal data. The demo dataset and screenshots use fictional or synthetic content.
Designed & built by Saby N.
(sabynextdoor) · © 2026
{ "id": 10, "risk_score": 91, "risk_level": "CRITICAL", "company": "DreamJob LLP", "indicators": [ { "title": "Payment Requested", "severity": "CRITICAL", "detail": "…" } ], "verification": [ /* 8-item verification checklist */ ], "recommendation": "…", "created_at": "2026-09-20T00:00:00" }