ScamGuard Documentation
Local-first scam detection for SMS, email, chat, and live phone calls.
These docs are enforced.
backend/tests/test_docs.pyfails if an API endpoint exists that api-reference.md does not document. Change the API → update the docs in the same commit.
Start here
| Page | What it covers |
|---|---|
| Architecture | How the three detection tiers fit together, and why |
| Detection rules | How to add or tune rules without touching code |
| Caller check | Checking the calling number against the caller's claim — agents, evidence store, production design |
| Safety invariants | Rules that must never regress, each from a real bug |
| Intelligence sync | Central brain / local brain, signed packs, on-device model |
| API reference | Every endpoint, with request/response shapes |
| Clients | Web, iOS, Android — capabilities per platform and the shared contract |
| Local development | Running the stack on your machine |
| Changelog | What changed, when, and why |
Working with Claude Code? CLAUDE.md at the repo root is the context file it reads automatically — architecture, safety invariants, commands, and the platform constraints that shape the clients.
What ScamGuard is
A detection engine with thin clients. The engine analyzes text — an SMS, a pasted email, a call transcript — and returns a structured verdict: risk index, category, the specific signals found, what the user should do, and an honest statement of what it could and could not check.
The product promise is not "we detect scams." It is "we warn you at the moment it matters, and we tell you the truth about our limits." That second half is why the codebase has coverage reporting, processing disclosure, and a review queue for the gray zone.
The one architectural rule
┌──────────────────────┐
web ────────────▶│ │
iOS ────────────▶│ backend/ (engine) │
Android ────────▶│ rules · claims · │
extension ──────▶│ scoring · LLM │
└──────────────────────┘
Detection logic exists once, in backend/. Clients are UI plus platform integration. The only exception is the iOS on-device rules engine, which is generated from the server's rules pack rather than hand-written — so it cannot drift.
Why this matters: the audit found the message and live-call paths had already drifted on claim detection, producing a severe false positive. They now share app/verify/claims.py. Forking the engine per platform would multiply that class of bug by the number of platforms.
Current status
- Backend test suite fully offline — no network, no Ollama, no keys. It also checks the served web page: capability gating, the verdict headline's safety rules, and that only verified phone numbers appear in its help text.
- Web app ready for a soft launch; Android implemented; iOS runnable.
- Not yet production-ready as a background filter: the risk index needs a labelled evaluation set with per-language precision and recall before it can be read as a probability. See the release gate in safety-invariants.md.