ScamGuard Documentation

Local-first scam detection for SMS, email, chat, and live phone calls.

These docs are enforced. backend/tests/test_docs.py fails if an API endpoint exists that api-reference.md does not document. Change the API → update the docs in the same commit.

Start here

PageWhat it covers
ArchitectureHow the three detection tiers fit together, and why
Detection rulesHow to add or tune rules without touching code
Caller checkChecking the calling number against the caller's claim — agents, evidence store, production design
Safety invariantsRules that must never regress, each from a real bug
Intelligence syncCentral brain / local brain, signed packs, on-device model
API referenceEvery endpoint, with request/response shapes
ClientsWeb, iOS, Android — capabilities per platform and the shared contract
Local developmentRunning the stack on your machine
ChangelogWhat 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