Clients

One engine, three front-ends. Detection logic lives only in backend/; every client is UI plus platform integration over the /v1 API.

ClientStatusLocation
WebSoft launch — check, report, scam patterns, privacy/terms; capability-gated (plan)clients/web/
iOS (Swift/SwiftUI)v0.2 — API client, recording ingest, signed rules-pack sync, ILMessageFilterExtension (SMS filtering)clients/ios/
Android (Kotlin/Compose)Implemented — SMS protection, call listening, share targetclients/android/

The one exception to "no logic in clients"

Mobile SMS filtering must answer offline, in milliseconds — an iOS ILMessageFilterExtension has no network by default, and an Android SmsReceiver runs before the user sees anything. So both mobile clients embed a deterministic rules engine.

That engine is generated from server data, not hand-written:


backend/rules/*.yaml  →  GET /v1/rules/pack  →  device
                          (rules + entities + scoring floors)

Both implementations reproduce the server's aggregation exactly — diminishing returns 1 − Π(1 − wᵢ), exclude-span containment, critical floor at 0.85 — and read their thresholds from the pack rather than hard-coding them. Adding a rule in YAML updates every platform on next sync, with no app release.

Never hard-code a rule in Swift or Kotlin. That is the drift the audit caught inside a single codebase; across three platforms it would be unmanageable.

Platform capability matrix

What each platform can actually do, which is what drives the differing roadmaps:

CapabilityWebiOSAndroid
Paste/share text for analysis✅✅ Share Extension✅ Share target
Read incoming SMS automatically❌⚠️ ILMessageFilterExtension sees sender + body, but only for senders not in Contacts, and can only return allow/junk/none — no custom notification, no explanation shown✅ full content via RECEIVE_SMS, any sender
Screen calls before pickup❌⚠️ block-list only (CallKit)✅ CallScreeningService
Access live call audio❌❌ no API❌ blocked since Android 10 (probed at runtime)
Start listening automatically on an incoming call❌❌✅ via CallScreeningService
Speakerphone live analysis✅ beta — desktop Chrome/Edge; a phone can't listen to its own call✅ consent-gated✅ foreground service
Analyze a recorded call✅ upload — tab shown only when the server has transcription✅✅
On-device transcription⚠️ browser vendor may process remotely✅ SFSpeechRecognizer✅ SpeechRecognizer

Android is the strongest platform for this product. Full SMS content access means real background protection; iOS deliberately cannot match it. Plan the Android SMS receiver as the flagship feature, not a port of the iOS app.

Call recording

Neither platform lets a third-party app tap live call audio. Every App Store or Play Store app claiming "call recording" uses a workaround. The honest options, and which ones ScamGuard uses, are documented per platform:

All routes converge on the same two backend endpoints, so no backend work is needed to support them: POST /v1/analyze/voice for files, and the /v1/call/* session flow for live transcripts.

Shared client contract

Every client must honour these, or it misrepresents the engine:

  1. Respect coverage. If coverage != "full", a low risk_score is not evidence of safety — show coverage_note prominently.
  2. Call it a risk index. Never render risk_score as a percentage likelihood; it is uncalibrated. See safety invariants.
  3. Surface processing. Tell the user what stayed on-device and what left it.
  4. Consent before online checks. user_consent_online_checks must reflect an explicit user choice, never a default.
  5. Feature-detect via /v1/capabilities instead of assuming a deployment has the LLM, voice transcription, or online checks enabled.
  6. Cancel live-call sessions on background/unload (POST /v1/call/{id}/cancel) so transcripts are purged rather than waiting for TTL expiry.

Adding a new client

  1. Generate models from /openapi.json (do not hand-write them if avoidable).
  2. Implement the shared contract above.
  3. If the platform needs offline checks, consume /v1/rules/pack — do not port rules by hand.
  4. Add the platform to the capability matrix on this page.

Web client notes

The web app reads GET /v1/capabilities at start-up and only offers what the server can back: the recording tab exists only with transcription installed, the third-party-lookups box only when lookups are enabled, and the advisor chat only when AI is available. Operator-facing detail (why AI is off, how to fix it) appears only on localhost — never to visitors.

Pages: Check · Report · Scam patterns · How it works · Privacy · Terms. The Privacy page is written against the code; tests/test_web_client.py fails if the retention and storage claims it makes stop matching the settings.