System Requirements Document for guardianshield-scam-interception

1. Introduction

GuardianShield is an autonomous, on-device scam interception platform for elderly users. It detects social engineering — impersonation, OTP harvesting, and manufactured urgency — in real time on Android devices and physically interrupts fraudulent transactions using OS-level UI takeovers. It also provides a "Caregiver Circuit Breaker" that lets a family member remotely kill an active transaction on the senior's device through a low-latency cloud relay.

The product serves two audiences:

• Elderly User (Protected Senior) — the person whose Android device runs the on-device scam classifier and accessibility node scanner. Their goal is to be shielded from social-engineering fraud without having to recognize the scam themselves.
• Caregiver (Family Circuit Breaker) — a family member who receives high-priority threat alerts on their own Android device and acts as the remote circuit breaker.

The system is delivered as three components: an Elderly Victim Android App (Kotlin, Coroutines, Jetpack, ONNX Runtime Mobile, Android Accessibility APIs, WindowManager, Notifications API), a Caregiver Android App (Kotlin, Firebase Cloud Messaging, OkHttp), and a Cloud Relay Server (Go, Gorilla WebSockets, Firebase Admin SDK).

2. System Overview

GuardianShield operates as a closed loop across three components:

1. Edge detection (senior device). The senior's Android app tokenizes on-screen text locally with a WordPiece tokenizer (max sequence length 64) and classifies it with an INT8 ONNX model (scam_classifier_int8.ort) to produce a Softmax threat probability across categories such as OTP_HARVESTING and AUTHORITY_IMPERSONATION. An accessibility service crawls rootInActiveWindow (depth-limited) for targeted packages such as com.google.android.dialer and net.one97.paytm, matching urgency + financial keyword patterns. No text or audio is sent to the cloud.
2. Intervention (senior device). When a threat is confirmed, the app physically interrupts the transaction using two UI fallbacks: a TYPE_ACCESSIBILITY_OVERLAY floating overlay with a "Hold 3s to Dismiss" control for non-secure apps, and an EmergencyInterventionActivity full-screen intent for protected banking apps that use setHideOverlayWindows(true) and FLAG_SECURE. A FullScreenAlertDispatcher raises a high-importance notification channel with AudioAttributes.USAGE_ALARM to bypass Do Not Disturb.
3. Circuit breaker (relay + caregiver). The senior app raises an alert to the Go relay (POST /api/v1/alert/raise), which dispatches a high-priority FCM data message to the caregiver. The caregiver taps "\xf0\x9f\x9b\x91 KILL TRANSACTION NOW", which fires an asynchronous OkHttp POST to POST /api/v1/alert/respond; the relay looks up the senior's WebSocket by device_id and pushes { "command": "LOCK_NOW" } down the socket. The senior app executes performGlobalAction(GLOBAL_ACTION_HOME) and GLOBAL_ACTION_LOCK_SCREEN (API 28+).

2a. Product Interpretation and Delivery Boundary

Delivery ownership. GuardianShield is delivered as first-party custom UI on both Android apps plus a first-party Go relay. The senior's device owns all detection and intervention; the relay owns alert fan-out and WebSocket continuity; the caregiver's device owns alert receipt and the remote kill action. Firebase Cloud Messaging is a provider-owned transport used only for alert delivery to the caregiver — it is not a GuardianShield destination.

Identity and access. Both the senior and the caregiver use the GuardianShield application with self-service enrollment and returning verification. The senior's Protection and Intervention surfaces are restricted to the senior's own device session; the caregiver's Alerts and Circuit Breaker surfaces are restricted to the caregiver's own session. Role-aware authorization separates senior-device protection controls from caregiver remote-lock controls. The Landing surface is anonymously reachable; Sign Up and Login are the anonymous entry boundaries that establish access to protected surfaces.

Current vs. future. All behavior described in this document is current. No future-horizon capabilities are accepted at this time.

Exclusions. GuardianShield does not send text or audio to the cloud for scam detection. It does not provide account-management capabilities beyond self-service enrollment and returning verification. It does not provide differentiated permissions beyond the senior/caregiver role separation described above.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression explaining GuardianShield, its elderly-user protection purpose, on-device detection, and the caregiver circuit breaker. Displays the live Threat Dial as the dominant element, a vertical device-status rail (session ID, device, last heartbeat), and a ruled alert log (timestamped threat lines such as 14:02:11 · OTP_HARVESTING · 0.91).
• Primary action: "Open caregiver console" CTA in amber on graphite, leading to Login (or Sign Up for new users).
• Supporting actions: Navigate to Sign Up; navigate to Login.
• Domain entities: Threat session (session ID, device ID, heartbeat), threat category, confidence score.
• Component responsibilities: Threat Dial (circular gauge with needle sweep and tabular count-up), device-status rail (condensed uppercase with hairline dividers), ruled alert log (newest at top, 40ms stagger), titanium macro imagery layer (ambient parallax), topographic contour substrate.
• States: Loading (dial sweeps to final value, log populates with stagger); empty (dial at zero, log shows no active sessions); success (dial at session confidence, log populated); error (dial renders at final value, log shows last known entries); recovery (reduced-motion renders final state without sweep or parallax).

Sign Up

• Information/state: Self-service enrollment form for both the Elderly User (Protected Senior) and the Caregiver (Family Circuit Breaker). Role selection determines which protected surfaces become available after enrollment.
• Primary action: Create account and proceed to the role-appropriate protected surface (Protection for senior, Alerts for caregiver).
• Supporting actions: Switch to Login; return to Landing.
• Domain entities: Account identity, role (senior or caregiver), device binding.
• Component responsibilities: Role selector, credential fields, validation feedback, submission control.
• States: Loading (submission in progress); empty (initial form); success (account created, redirected to protected surface); error (validation or enrollment failure with inline message); recovery (retry submission without losing entered values).

Login

• Information/state: Returning verification for both the Elderly User (Protected Senior) and the Caregiver (Family Circuit Breaker).
• Primary action: Verify identity and proceed to the role-appropriate protected surface.
• Supporting actions: Switch to Sign Up; return to Landing.
• Domain entities: Account identity, role, session continuity.
• Component responsibilities: Credential fields, validation feedback, submission control.
• States: Loading (verification in progress); empty (initial form); success (verified, redirected to protected surface); error (invalid credentials with inline message); recovery (retry without losing entered values).

Protection

• Information/state: The senior's recurring on-device classification and accessibility monitoring workflow. Shows monitoring status, targeted package coverage, and the current session's threat confidence.
• Primary action: Enable or confirm accessibility monitoring and on-device classification.
• Supporting actions: Review targeted package list; review recent on-device detections.
• Domain entities: Monitoring session, targeted package, threat category, confidence score, device ID.
• Component responsibilities: Monitoring status indicator, package coverage list, confidence readout, accessibility-service binding status.
• States: Loading (monitoring status resolving); empty (no monitoring session active); success (monitoring active, packages covered); error (accessibility service not bound or model unavailable); recovery (re-enable monitoring or rebind accessibility service).

Intervention

• Information/state: Threat interruption, overlay dismissal, protected-app emergency presentation, and alarm-priority alert handling on the senior device. Shows the active threat category, confidence, and the intervention surface in use (overlay or full-screen).
• Primary action: Acknowledge the intervention by holding 3 seconds to dismiss the non-secure overlay, or acknowledge the full-screen emergency alert.
• Supporting actions: Review the threat detail; allow the caregiver circuit breaker to complete remotely.
• Domain entities: Threat session, threat category, confidence score, intervention surface type.
• Component responsibilities: ScamOverlayManager (TYPE_ACCESSIBILITY_OVERLAY with "Hold 3s to Dismiss" and circular amber progress ring), EmergencyInterventionActivity (USE_FULL_SCREEN_INTENT), FullScreenAlertDispatcher (high-importance channel with AudioAttributes.USAGE_ALARM), remote LOCK_NOW handler (GLOBAL_ACTION_HOME + GLOBAL_ACTION_LOCK_SCREEN on API 28+).
• States: Loading (intervention surface preparing); empty (no active threat); success (threat interrupted, transaction blocked); error (overlay blocked by setHideOverlayWindows or FLAG_SECURE, full-screen intent unavailable); recovery (fall back to the alternate intervention surface, or complete remote lock via the relay).

Alerts

• Information/state: Caregiver receipt and review of high-priority threat alerts with session and threat context. Each alert shows session ID, elderly device ID, threat category, and timestamp.
• Primary action: Open an alert to review its context and proceed to the Circuit Breaker action.
• Supporting actions: Review alert history; return to the alert list.
• Domain entities: Alert (session ID, elderly device ID, caregiver FCM token, threat category), threat session.
• Component responsibilities: FirebaseMessagingService (receives high-priority FCM data messages), NotificationCompat with PRIORITY_MAX and the "\xf0\x9f\x9b\x91 KILL TRANSACTION NOW" action button, alert list with ruled rows.
• States: Loading (alert list resolving); empty (no alerts received); success (alerts listed with session and threat context); error (FCM delivery failure or relay unreachable); recovery (retry delivery or refresh the alert list).

Circuit Breaker

• Information/state: The caregiver's focused remote LOCK_NOW action and its return/completion context. Shows the active threat session, the senior's device ID, and the outcome of the remote lock.
• Primary action: Tap "\xf0\x9f\x9b\x91 KILL TRANSACTION NOW" to fire the asynchronous OkHttp POST to POST /api/v1/alert/respond with the LOCK_NOW action.
• Supporting actions: Review the session context before acting; return to Alerts.
• Domain entities: Threat session, elderly device ID, LOCK_NOW command, relay response.
• Component responsibilities: RemoteLockActionReceiver (BroadcastReceiver wired to the notification action), asynchronous OkHttp client, relay response handler, confirmation display.
• States: Loading (LOCK_NOW POST in flight); empty (no active session to lock); success (relay confirmed LOCK_NOW pushed down the senior's WebSocket); error (relay unreachable or WebSocket not found for the device ID); recovery (retry the LOCK_NOW POST or return to Alerts for updated context).

3. Functional Requirements

On-Device Edge ML Pipeline

• As an Elderly User (Protected Senior), I should have all scam detection processing happen locally on my device using onnxruntime-android, so that no text or audio is ever sent to the cloud. (provenance: explicit; lifecycle: trigger = on-screen text captured by the accessibility service; input = raw text; result = local classification only; failure/recovery = model unavailable, retry on next event; continuation = monitoring continues; access = senior device session)
• As an Elderly User (Protected Senior), I should have my on-screen text tokenized by a lightweight on-device WordPiece tokenizer that loads from vocab.txt and handles [CLS], [SEP], [UNK], and [PAD], with a maximum sequence length of 64, so that classification input is bounded and consistent. (provenance: explicit; lifecycle: trigger = text captured; input = raw text; result = tokenized input_ids and attention_mask; failure/recovery = unknown tokens mapped to [UNK], sequence truncated to 64; continuation = classification proceeds; access = senior device session)
• As an Elderly User (Protected Senior), I should have an OnnxScamClassifier that takes the tokenized input_ids and attention_mask, feeds them into scam_classifier_int8.ort via OnnxTensor, and computes a Softmax probability to identify threats such as OTP_HARVESTING and AUTHORITY_IMPERSONATION. (provenance: explicit; lifecycle: trigger = tokenized input available; input = input_ids, attention_mask; result = Softmax probability and threat category; failure/recovery = inference error, retry on next event; continuation = threat decision proceeds; access = senior device session)
• As an Elderly User (Protected Senior), I should have all native ONNX tensors properly closed after use, so that memory leaks outside the JVM GC do not accumulate. (provenance: explicit; lifecycle: trigger = inference completes; input = native tensor handles; result = tensors closed; failure/recovery = close in finally block; continuation = next inference proceeds; access = senior device session)

Accessibility Service (Node Scanner & Interceptor)

• As an Elderly User (Protected Senior), I should have a ScamGuardianAccessibilityService extending AccessibilityService, bound to android.permission.BIND_ACCESSIBILITY_SERVICE with accessibilityEventTypes="typeWindowStateChanged|typeWindowContentChanged". (provenance: explicit; lifecycle: trigger = accessibility event; input = window state/content change; result = service receives event; failure/recovery = service not bound, prompt rebind; continuation = monitoring continues; access = senior device session)
• As an Elderly User (Protected Senior), I should have the service crawl rootInActiveWindow with depth limited to avoid memory churn, for targeted packages such as com.google.android.dialer and net.one97.paytm, looking for regex/string matches combining urgency + financial keywords. (provenance: explicit; lifecycle: trigger = window event on targeted package; input = node tree; result = matched urgency + financial keyword combination; failure/recovery = depth limit reached, stop crawl; continuation = classification proceeds; access = senior device session)
• As an Elderly User (Protected Senior), I should have the service listen for a WebSocket callback command LOCK_NOW and, on receipt, execute performGlobalAction(GLOBAL_ACTION_HOME) and GLOBAL_ACTION_LOCK_SCREEN (API 28+). (provenance: explicit; lifecycle: trigger = LOCK_NOW received over WebSocket; input = command; result = home action and lock screen executed; failure/recovery = API below 28, home action still executes; continuation = device locked; access = senior device session)

Unblockable UI Intervention (Anti-Tapjacking Fallback)

• As an Elderly User (Protected Senior), I should have a ScamOverlayManager that presents a standard floating overlay using TYPE_ACCESSIBILITY_OVERLAY for non-secure apps, including a "Hold 3s to Dismiss" button to introduce cognitive friction. (provenance: explicit; lifecycle: trigger = threat confirmed on non-secure app; input = threat decision; result = overlay shown with hold-to-dismiss; failure/recovery = overlay blocked, fall back to full-screen intent; continuation = senior dismisses or accepts warning; access = senior device session)
• As an Elderly User (Protected Senior), I should have an EmergencyInterventionActivity for protected banking apps that uses USE_FULL_SCREEN_INTENT. (provenance: explicit; lifecycle: trigger = threat confirmed on protected banking app; input = threat decision; result = full-screen emergency activity shown; failure/recovery = full-screen intent unavailable, fall back to overlay; continuation = senior acknowledges alert; access = senior device session)
• As an Elderly User (Protected Senior), I should have a FullScreenAlertDispatcher that triggers the full-screen intent using a high-importance NotificationChannel with AudioAttributes.USAGE_ALARM to bypass Android Do Not Disturb modes. (provenance: explicit; lifecycle: trigger = threat confirmed; input = threat decision; result = high-importance notification with alarm audio attributes; failure/recovery = channel blocked, retry with alternate channel; continuation = senior sees alert; access = senior device session)

Go Cloud Relay (Circuit Breaker)

• As a Caregiver (Family Circuit Breaker), I should have the relay expose GET /ws?device_id=XYZ that upgrades to WebSocket and stores the active connection in a concurrency-safe map[string]*websocket.Conn protected by a sync.RWMutex. (provenance: explicit; lifecycle: trigger = senior device connects; input = device_id; result = connection stored; failure/recovery = connection dropped, re-register on reconnect; continuation = relay can push commands; access = relay system process)
• As a Caregiver (Family Circuit Breaker), I should have the relay expose POST /api/v1/alert/raise that receives the threat payload from the senior's app and dispatches a High-Priority FCM Data Message to the caregiver. (provenance: explicit; lifecycle: trigger = senior app raises alert; input = AlertPayload; result = FCM data message dispatched; failure/recovery = FCM dispatch failure, retry; continuation = caregiver receives alert; access = relay system process)
• As a Caregiver (Family Circuit Breaker), I should have the relay expose POST /api/v1/alert/respond that receives LOCK_NOW from the caregiver, looks up the WebSocket connection by device_id, and immediately pushes the { "command": "LOCK_NOW" } JSON down the socket. (provenance: explicit; lifecycle: trigger = caregiver sends LOCK_NOW; input = device_id and action; result = command pushed down socket; failure/recovery = WebSocket not found, return error to caregiver; continuation = senior device executes lock; access = relay system process)
• As a Caregiver (Family Circuit Breaker), I should have the relay use an AlertPayload struct with omitempty and pointers for optional JSON fields (SessionID, ElderlyDeviceID, CaregiverFCM, ThreatCategory). (provenance: explicit; lifecycle: trigger = payload serialization; input = struct fields; result = optional fields omitted when empty; failure/recovery = malformed payload rejected; continuation = relay processes valid payloads; access = relay system process)

Caregiver App (Push Notification Receiver & Action Dispatcher)

• As a Caregiver (Family Circuit Breaker), I should have a FirebaseMessagingService that receives high-priority threat alerts. (provenance: explicit; lifecycle: trigger = FCM data message arrives; input = alert payload; result = alert received; failure/recovery = FCM delivery failure, retry; continuation = notification constructed; access = caregiver session)
• As a Caregiver (Family Circuit Breaker), I should have a NotificationCompat with PRIORITY_MAX and an embedded action button "\xf0\x9f\x9b\x91 KILL TRANSACTION NOW" constructed when an alert arrives. (provenance: explicit; lifecycle: trigger = alert received; input = alert payload; result = high-priority notification with action button; failure/recovery = notification channel blocked, retry; continuation = caregiver sees notification; access = caregiver session)
• As a Caregiver (Family Circuit Breaker), I should have the action button wired to a BroadcastReceiver (RemoteLockActionReceiver) that executes an asynchronous OkHttp POST request back to the Go relay's /api/v1/alert/respond endpoint with the LOCK_NOW action. (provenance: explicit; lifecycle: trigger = caregiver taps action button; input = tap; result = asynchronous POST with LOCK_NOW; failure/recovery = relay unreachable, retry; continuation = relay pushes LOCK_NOW to senior device; access = caregiver session)

Identity and Access

• As an Elderly User (Protected Senior) or a Caregiver (Family Circuit Breaker), I should be able to self-enroll with a role selection that determines which protected surfaces become available. (provenance: required_inference; lifecycle: trigger = first use; input = role and credentials; result = account created; failure/recovery = validation error, retry; continuation = redirected to role-appropriate protected surface; access = anonymous entry)
• As an Elderly User (Protected Senior) or a Caregiver (Family Circuit Breaker), I should be able to verify my identity on return to regain access to protected monitoring and circuit-breaker workflows. (provenance: required_inference; lifecycle: trigger = returning use; input = credentials; result = session established; failure/recovery = invalid credentials, retry; continuation = redirected to role-appropriate protected surface; access = anonymous entry)
• As an Elderly User (Protected Senior), I should have my Protection and Intervention surfaces restricted to my own device session. (provenance: required_inference; lifecycle: trigger = access attempt; input = session identity; result = access granted or denied; failure/recovery = denied, redirect to Login; continuation = senior uses protection surfaces; access = role_restricted)
• As a Caregiver (Family Circuit Breaker), I should have my Alerts and Circuit Breaker surfaces restricted to my own session. (provenance: required_inference; lifecycle: trigger = access attempt; input = session identity; result = access granted or denied; failure/recovery = denied, redirect to Login; continuation = caregiver uses circuit-breaker surfaces; access = role_restricted)

4. User Personas

Elderly User (Protected Senior)

• Product context: The senior is the protected party whose Android device runs the on-device scam classifier and accessibility node scanner. They use their phone normally while the app monitors targeted packages such as com.google.android.dialer and net.one97.paytm.
• Primary goal: To be shielded from social-engineering fraud (impersonation, OTP harvesting, urgency) without having to recognize the scam themselves.
• Distinct accepted responsibilities: Use their phone normally while the app monitors targeted packages; respond to the intervention UI by holding 3 seconds to dismiss a non-secure overlay or acknowledging the full-screen emergency alert.
• Relevant inputs or decisions: Whether to dismiss the overlay (hold 3s) or acknowledge the full-screen alert; whether to accept the warning or proceed.
• Interactions with other accepted participants: The senior's device raises alerts to the relay, which dispatches them to the caregiver. The caregiver may remotely lock the senior's device via the circuit breaker.
• Observable success: The fraudulent transaction is interrupted on their device and they remain in control of dismissing or accepting the warning.
• What makes this role different: The senior does not initiate detection or intervention — the system acts autonomously on their behalf. Their only active decision is whether to dismiss or accept the warning, and that decision is deliberately made harder by the "Hold 3s to Dismiss" cognitive friction.

Caregiver (Family Circuit Breaker)

• Product context: A family member who receives high-priority FCM threat alerts on their own Android device and acts as the remote circuit breaker.
• Primary goal: To kill an active fraudulent transaction on the senior's device with low latency.
• Distinct accepted responsibilities: Receive the alert notification with threat category and session context; tap the "\xf0\x9f\x9b\x91 KILL TRANSACTION NOW" action to POST LOCK_NOW to the relay.
• Relevant inputs or decisions: Whether to tap the kill action; whether to review the session context before acting.
• Interactions with other accepted participants: The caregiver receives alerts raised by the senior's device via the relay, and their kill action is pushed down the senior's WebSocket for execution.
• Observable success: The senior's active transaction is killed remotely with low latency, confirmed by the relay pushing LOCK_NOW down the device WebSocket.
• What makes this role different: The caregiver acts remotely and under time pressure, with a single decisive action. Their interface must surface threat context in under a second and make the kill action unmissable.

5. Core User Flows

Flow 1: Senior enrolls and enables protection

1. The Elderly User (Protected Senior) opens GuardianShield for the first time and lands on the Landing page, which explains on-device detection and the caregiver circuit breaker.
2. The senior taps "Open caregiver console" or navigates to Sign Up.
3. On Sign Up, the senior selects the senior role and enters credentials.
4. The account is created and the senior is redirected to Protection.
5. On Protection, the senior enables accessibility monitoring and on-device classification. The app binds ScamGuardianAccessibilityService to android.permission.BIND_ACCESSIBILITY_SERVICE with accessibilityEventTypes="typeWindowStateChanged|typeWindowContentChanged".
6. Observable result: Monitoring status shows active, targeted packages are covered, and the confidence readout is live.
7. Failure/recovery: If the accessibility service is not bound or the model is unavailable, the senior is prompted to rebind or retry.
8. Continuation: The senior uses their phone normally while monitoring runs.

Flow 2: Senior returns and regains protection access

1. The senior opens GuardianShield and lands on Login.
2. The senior enters credentials and verifies identity.
3. Observable result: The senior is redirected to Protection with monitoring status restored.
4. Failure/recovery: Invalid credentials show an inline message and allow retry without losing entered values.
5. Continuation: The senior resumes normal phone use under monitoring.

Flow 3: On-device detection and intervention on a non-secure app

1. The senior is using a non-secure app (for example, com.google.android.dialer).
2. The accessibility service receives a typeWindowStateChanged or typeWindowContentChanged event and crawls rootInActiveWindow with depth limited to avoid memory churn.
3. The service matches urgency + financial keywords and passes the text to the on-device WordPiece tokenizer (max sequence length 64, handling [CLS], [SEP], [UNK], [PAD]).
4. OnnxScamClassifier feeds input_ids and attention_mask into scam_classifier_int8.ort via OnnxTensor, computes a Softmax probability, and identifies a threat category such as OTP_HARVESTING or AUTHORITY_IMPERSONATION. All native ONNX tensors are closed after use.
5. The Intervention page presents ScamOverlayManager as a TYPE_ACCESSIBILITY_OVERLAY floating overlay with a "Hold 3s to Dismiss" button.
6. Observable result: The senior sees the overlay with a circular amber progress ring around the hold target.
7. Failure/recovery: If the overlay is blocked, the system falls back to the full-screen intent.
8. Continuation: The senior either holds 3 seconds to dismiss or accepts the warning; the transaction is interrupted.

Flow 4: On-device detection and intervention on a protected banking app

1. The senior is using a protected banking app (for example, net.one97.paytm) that uses setHideOverlayWindows(true) and FLAG_SECURE.
2. The accessibility service detects urgency + financial keywords and the on-device classifier identifies a threat.
3. The Intervention page presents EmergencyInterventionActivity via USE_FULL_SCREEN_INTENT.
4. FullScreenAlertDispatcher triggers the full-screen intent using a high-importance NotificationChannel with AudioAttributes.USAGE_ALARM to bypass Do Not Disturb.
5. Observable result: The senior sees the full-screen emergency alert.
6. Failure/recovery: If the full-screen intent is unavailable, the system falls back to the overlay.
7. Continuation: The senior acknowledges the alert; the transaction is interrupted.

Flow 5: Caregiver receives an alert

1. The senior's device raises an alert to the relay via POST /api/v1/alert/raise with an AlertPayload containing SessionID, ElderlyDeviceID, CaregiverFCM, and ThreatCategory.
2. The relay dispatches a High-Priority FCM Data Message to the caregiver.
3. The caregiver's FirebaseMessagingService receives the alert and constructs a NotificationCompat with PRIORITY_MAX and the "\xf0\x9f\x9b\x91 KILL TRANSACTION NOW" action button.
4. Observable result: The caregiver sees the high-priority notification with session and threat context.
5. Failure/recovery: If FCM delivery fails, the relay retries; the caregiver can refresh the Alerts page.
6. Continuation: The caregiver opens Alerts to review the alert context.

Flow 6: Caregiver remotely kills an active transaction

1. The caregiver opens Alerts and reviews the alert with session ID, elderly device ID, threat category, and timestamp.
2. The caregiver proceeds to Circuit Breaker, which shows the active threat session and the senior's device ID.
3. The caregiver taps "\xf0\x9f\x9b\x91 KILL TRANSACTION NOW".
4. RemoteLockActionReceiver executes an asynchronous OkHttp POST to POST /api/v1/alert/respond with the LOCK_NOW action.
5. The relay looks up the WebSocket connection by device_id and immediately pushes { "command": "LOCK_NOW" } down the socket.
6. The senior's device receives LOCK_NOW and executes performGlobalAction(GLOBAL_ACTION_HOME) and GLOBAL_ACTION_LOCK_SCREEN (API 28+).
7. Observable result: The senior's device returns to home and locks; the caregiver sees confirmation that the relay pushed LOCK_NOW.
8. Failure/recovery: If the relay is unreachable or the WebSocket is not found for the device ID, the caregiver sees an error and can retry the POST or return to Alerts for updated context.
9. Continuation: The caregiver returns to Alerts to monitor for further threats.

Flow 7: Caregiver enrolls and returns

1. The Caregiver (Family Circuit Breaker) opens GuardianShield and lands on Landing.
2. The caregiver navigates to Sign Up, selects the caregiver role, and enters credentials.
3. Observable result: The account is created and the caregiver is redirected to Alerts.
4. On return, the caregiver lands on Login, verifies identity, and is redirected to Alerts.
5. Failure/recovery: Invalid credentials show an inline message and allow retry.
6. Continuation: The caregiver monitors Alerts for high-priority threat notifications.

6. Visuals Colors and Theme

Muse: MARQ by Garmin — luxury instrument aesthetic. GuardianShield is a precision instrument in a crisis: a dark cockpit display that tells a worried son or daughter, in under a second, that their mother's transaction was intercepted. Trust, gravity, and legibility under stress; the senior's screen must feel like a calm, authoritative device, not a warning banner.

Headline: Titanium instrumentation for a guardian that never sleeps.

Color Tokens (Dark Mode)

Proportion: 70% graphite, 20% steel surface, 8% bone type, 2% gold + teal combined. No blue anywhere; the only cool note is the teal signal, which reads as instrument glass, not SaaS chrome.

Typography

• Headings: Barlow Condensed, 600–700 weight. Uppercase for data labels and threat categories with +0.14em tracking; sentence-case for the hero statement at 700. Tight leading (0.92) on display sizes so stacked headlines read as a machined stack.
• Body: Saira.
• Numerals: Always tabular, always Saira's mono-adjacent figures, set large as the instrument's readout.
• Scale: 1.25 modular with a display ramp — hero clamp(44px, 9vw, 128px) / section clamp(30px, 5vw, 56px) / subhead 24px / body 17px / label 13px uppercase +0.14em / readout numerals clamp(36px, 7vw, 84px) tabular.

Shape Language

Circular gauges and bezels as the primary geometry; ruled data rows with hairline 1px #2A2F36 dividers; rectangles with 4px radii only (no pills, no blobs) so every surface reads as machined plate. Concentric ring motifs for threat confidence; a single amber "needle" sweep as the only curved motion. Edges are hard; radii are functional, never decorative.

Layout

A 12-column instrument grid on graphite. Left rail: vertical device/status strip (session ID, device, last heartbeat) in condensed uppercase. Centre: the live Threat Dial — a large circular gauge with the current session's confidence score as a needle. Right rail: ruled alert log, newest at top, each row a timestamped hash-like line. Below the fold, edge-to-edge macro photography of titanium and sapphire with a single ruled caption. No centred SaaS hero; the composition is asymmetric and instrument-panel-like, with the gauge as the dominant element and the CTA pinned beneath it in the amber accent.

Imagery

Macro photography of brushed titanium, sapphire crystal, and a watch bezel at extreme close range, lit with a single hard key so the material's grain is visible; topographic contour lines as a recurring diagram motif behind data; no stock people, no illustrated characters, no gradient blobs. The "device" imagery is the instrument itself — the phone as a precision tool — plus schematic diagrams of the interception flow rendered as an engineering drawing.

7. Signature Design Concept

The public entry (Landing) is composed as a cockpit, not a landing page:

• Full-bleed graphite field, no centred stack. The dominant element is a 560px Threat Dial anchored left-of-centre at 1280px (280px at 375px), its bezel a 1px champagne ring on a #161A1F plate, needle at 78% confidence in amber, with the tabular readout "78" set in Saira at clamp(36px, 7vw, 84px) inside the dial.
• To its right, a two-line condensed headline "SOCIAL ENGINEERING / INTERCEPTED" in Barlow Condensed 700, clamp(44px, 9vw, 128px), stacked flush-left and allowed to run to the viewport edge.
• Beneath the dial, the CTA "Open caregiver console" sits in amber on graphite, and the sub-line "On-device. Nothing leaves the phone." in muted steel.
• A vertical device-status rail runs down the far left; a ruled alert log runs down the far right.
• A titanium macro photograph bleeds off the bottom-right corner at 40% opacity, cropped by the viewport, never covering the dial, headline, CTA, or log text.

This hero could not be mistaken for SaaS: it is a cockpit, not a landing page. The signature moves are the live Threat Dial, the vertical instrument rail, the ruled alert log with 40ms stagger, the "Hold 3s to Dismiss" takeover presented as a machined bezel with a circular amber progress ring, and the topographic contour line pattern drawn at 1px in #2A2F36 running behind the dial and the log.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: dimensional_css

Landing Hero Motion Brief

• Focal subject: The live Threat Dial — a 1px champagne ring on a brushed-steel plate with a needle that sweeps to the session's confidence score and a tabular numeral that counts up inside it.
• Input → transformation → outcome thesis: On load, the dial's needle sweeps from zero to the session's confidence score with a physical ease-out (600ms, cubic-bezier(0.16, 1, 0.3, 1)), the confidence numeral counts up in tabular figures, and the alert log rows slide in from the right with a 40ms stagger. The outcome is a cockpit that reads as a live instrument, not a marketing illustration.
• Motion vocabulary: Needle-sweep and count-up only. No bounce, no particles, no gradient drift. A slow 20s ambient parallax drifts the titanium macro layer behind the gauge.
• Composed first frame: Graphite field, dial at zero with needle at rest, headline stacked flush-left, CTA in amber beneath the dial, device-status rail on the far left, alert log empty on the far right, titanium macro bleeding off the bottom-right corner at 40% opacity.
• Reduced-motion state: The dial renders at its final value, the log appears fully populated, and the parallax is removed.

9. Non-Functional Requirements

• On-device processing: Do NOT send text or audio to the cloud; all scam detection processing must happen locally on the senior's device using onnxruntime-android. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Tokenizer bound: Max tokenizer sequence length is 64. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Crawl depth: Accessibility window crawl depth must be limited to avoid memory churn. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Native memory: All native ONNX tensors must be properly closed to prevent memory leaks outside the JVM GC. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• API level: GLOBAL_ACTION_LOCK_SCREEN requires API 28+. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Concurrency safety: The relay's WebSocket connection map must be concurrency-safe, protected by a sync.RWMutex. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Optional fields: AlertPayload optional JSON fields must use omitempty and pointers. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Alert priority: The caregiver notification must use PRIORITY_MAX and the full-screen alert must use a high-importance NotificationChannel with AudioAttributes.USAGE_ALARM. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Asynchronous POST: The caregiver's OkHttp POST to /api/v1/alert/respond must be asynchronous. (provenance: explicit; rationale: hard constraint in the authoritative user evidence)
• Stability and latency: The system must focus on extreme stability and low-latency execution, with thorough comments explaining platform workarounds (bypassing setHideOverlayWindows, intent flags for waking the screen, coroutine scopes). (provenance: explicit; rationale: hard constraint in the authoritative user evidence)

10. Tech Stack

• Elderly Victim Android App: Kotlin, Coroutines, Jetpack, ONNX Runtime Mobile, Android Accessibility APIs, WindowManager, Notifications API. (provenance: explicit)
• Caregiver Android App: Kotlin, Firebase Cloud Messaging (FCM), OkHttp. (provenance: explicit)
• Cloud Relay Server: Go (Golang), Gorilla WebSockets, Firebase Admin SDK. (provenance: explicit)
• On-device model: scam_classifier_int8.ort with vocab.txt for the WordPiece tokenizer. (provenance: explicit)
• Relay entry point: A single main.go file. (provenance: explicit)

11. Assumptions and Constraints

• Assumption: The senior's device runs Android API 28+ for GLOBAL_ACTION_LOCK_SCREEN to execute; on lower API levels, the home action still executes. (provenance: required_inference; rationale: explicit API 28+ constraint)
• Assumption: The senior's device has the accessibility service bound and the ONNX model available for detection to function. (provenance: required_inference; rationale: required for accepted detection lifecycle)
• Assumption: The caregiver's device has FCM delivery enabled and the relay is reachable for the kill action. (provenance: required_inference; rationale: required for accepted circuit-breaker lifecycle)
• Constraint: No text or audio is sent to the cloud. (provenance: explicit)
• Constraint: Max tokenizer sequence length is 64. (provenance: explicit)
• Constraint: Accessibility window crawl depth must be limited. (provenance: explicit)
• Constraint: All native ONNX tensors must be closed. (provenance: explicit)
• Constraint: GLOBAL_ACTION_LOCK_SCREEN requires API 28+. (provenance: explicit)
• Constraint: The relay's WebSocket map must be protected by a sync.RWMutex. (provenance: explicit)
• Constraint: AlertPayload optional fields must use omitempty and pointers. (provenance: explicit)
• Constraint: Caregiver notification must use PRIORITY_MAX; full-screen alert must use a high-importance channel with AudioAttributes.USAGE_ALARM. (provenance: explicit)
• Constraint: The caregiver's OkHttp POST must be asynchronous. (provenance: explicit)
• Constraint: Output must be delivered in the five specified sequential outputs with thorough comments explaining platform workarounds. (provenance: explicit)

12. Glossary

• GuardianShield: The autonomous on-device scam interception platform described in this document.
• Elderly User (Protected Senior): The protected party whose Android device runs the on-device scam classifier and accessibility node scanner.
• Caregiver (Family Circuit Breaker): A family member who receives high-priority threat alerts and can remotely kill an active transaction.
• Circuit Breaker: The caregiver's remote LOCK_NOW action that kills an active transaction on the senior's device.
• Threat Dial: The circular gauge on the Landing page that displays the current session's confidence score as a needle with a tabular readout.
• ScamGuardianAccessibilityService: The accessibility service that crawls rootInActiveWindow for targeted packages and matches urgency + financial keywords.
• OnnxScamClassifier: The on-device classifier that feeds tokenized input into scam_classifier_int8.ort and computes a Softmax probability.
• ScamOverlayManager: The TYPE_ACCESSIBILITY_OVERLAY floating overlay with a "Hold 3s to Dismiss" button for non-secure apps.
• EmergencyInterventionActivity: The full-screen intent activity for protected banking apps.
• FullScreenAlertDispatcher: The dispatcher that triggers the full-screen intent using a high-importance notification channel with AudioAttributes.USAGE_ALARM.
• AlertPayload: The relay's data contract with SessionID, ElderlyDeviceID, CaregiverFCM, and ThreatCategory fields.
• LOCK_NOW: The WebSocket callback command that triggers GLOBAL_ACTION_HOME and GLOBAL_ACTION_LOCK_SCREEN on the senior's device.
• RemoteLockActionReceiver: The BroadcastReceiver wired to the caregiver's notification action button that executes the asynchronous OkHttp POST.
• OTP_HARVESTING: A threat category for social engineering that attempts to extract one-time passwords.
• AUTHORITY_IMPERSONATION: A threat category for social engineering that impersonates an authority figure.
• TYPE_ACCESSIBILITY_OVERLAY: The Android window type used for the non-secure floating overlay.
• USE_FULL_SCREEN_INTENT: The Android intent flag used for the protected-app emergency activity.
• setHideOverlayWindows(true): The Android API that banking apps use to block normal floating windows.
• FLAG_SECURE: The Android flag that prevents screenshots and normal overlays on protected apps.
• GLOBAL_ACTION_HOME: The accessibility global action that returns the device to the home screen.
• GLOBAL_ACTION_LOCK_SCREEN: The accessibility global action that locks the device (API 28+).