Clients
One engine, three front-ends. Detection logic lives only in backend/; every client is UI plus platform integration over the /v1 API.
| Client | Status | Location |
|---|---|---|
| Web | Soft 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 target | clients/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:
| Capability | Web | iOS | Android |
|---|---|---|---|
| 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:
- iOS:
clients/ios/CALL_RECORDING.md— recommended route is Apple's native call recording (iOS 18.1+) exported from Notes and shared into the app via a Share Extension. - Android:
clients/android/CALL_LISTENING.md— recording is blocked since Android 10, so the app probes the device at runtime (CallAudioProbe) and falls back to speakerphone capture with on-device transcription. Using the Accessibility API for recording will get the app removed from Play, so it is deliberately not requested.
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:
- Respect
coverage. Ifcoverage != "full", a lowrisk_scoreis not evidence of safety — showcoverage_noteprominently. - Call it a risk index. Never render
risk_scoreas a percentage likelihood; it is uncalibrated. See safety invariants. - Surface
processing. Tell the user what stayed on-device and what left it. - Consent before online checks.
user_consent_online_checksmust reflect an explicit user choice, never a default. - Feature-detect via
/v1/capabilitiesinstead of assuming a deployment has the LLM, voice transcription, or online checks enabled. - 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
- Generate models from
/openapi.json(do not hand-write them if avoidable). - Implement the shared contract above.
- If the platform needs offline checks, consume
/v1/rules/pack— do not port rules by hand. - 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.