Isis Suspicious Activity Detection

Purpose#

Admin lane console that screens transactions for chargeback risk via the real anomaly-detection chargeback predictor. The feature-weighted model scores amount vs. the user's average, chargeback history, risky payment method, new device, new location, and account age into a probability + risk level + ranked factors. Unknown users are scored as new accounts against a baseline average amount.

Entry points#

• Embedded as the "Suspicious Activity Detection Lane" inside /studio/isis/anomaly-detection and /studio/isis/gpu-worker
• Studio index (/studio)
• Direct URL / bookmark currently returns the Studio Isis boundary hard-block until the segment is promoted; tests use ?__oshunStudioIsisLaneE2E=1 on localhost

Layout regions#

page.tsx mounts ShellLayout active="studio" and three panels (no breadcrumb panel).

• Workspace panel (data-isis-suspicious-activity-detection-workspace):
  • <h1> "Isis Suspicious Activity Detection Workspace" (WorkspaceHeading)
  • Summary paragraph (data-suspicious-summary)
  • Aggregate band (data-suspicious-aggregate): screen count, mean probability (data-suspicious-mean), and data-suspicious-band={level} chips
  • The "Screen a transaction" form (data-suspicious-form)
  • Screened-transaction list (data-suspicious-transactions) of data-suspicious-txn cards with data-suspicious-factors
• Route map panel (data-isis-suspicious-activity-detection-route-map): <h2> "Route Map" enumerating STUDIO_ISIS_SUSPICIOUS_ACTIVITY_DETECTION_ROUTE_MAP (5 entries) as data-isis-suspicious-activity-detection-route={path} articles
• Quick-actions panel (data-isis-suspicious-activity-detection-quick-actions, data-isis-suspicious-activity-detection-quick-action-count="2"): quickAction links to /studio/isis/creator-monetization and "Back to Studio workspace index" → /studio

States#

• Boundary hard-block — direct /studio/isis/suspicious-activity-detection returns 404 with x-studio-boundary: hard-block
• Anonymous redirect — E2E bypass URL redirects to /welcome before the workspace renders
• Loading — data-suspicious-loading "Loading screened transactions..."
• Unauthorized — data-suspicious-unauthorized (admin-scope fail-closed on 401/403, "Isis workspace scope required to screen suspicious activity.")
• Error — data-suspicious-error on non-OK / malformed response
• Ready (form) — aggregate + screen form + transaction list render; empty list shows data-suspicious-empty
• Result — data-suspicious-result with data-suspicious-status (ok / error), e.g. duplicate-transaction validation message
• Offline / malformed fail-closed — list network aborts, malformed list payloads, malformed screen successes, and screen network aborts render explicit error states without fabricating rows

Interactions#

Screen a transaction (data-suspicious-form)#

• Transaction id — data-suspicious-txnid text input
• User id — data-suspicious-userid text input
• Amount — data-suspicious-amount number input (min 0, step 0.01)
• Payment method — data-suspicious-method text input (defaults credit)
• Country (optional) — data-suspicious-country text input
• Device fingerprint (optional) — data-suspicious-device text input
• Screen transaction — data-suspicious-screen submit; POSTs to /v1/admin/isis/suspicious-activity, exposes data-suspicious-submit-state="idle|pending" and aria-busy, locks the form while pending, then reloads the list

Route map#

• Route-map articles ×5 — non-interactive path + purpose entries with data-isis-suspicious-activity-detection-route={path}

Quick-actions#

• Open Isis Creator Monetization workspace → /studio/isis/creator-monetization
• Back to Studio workspace index → /studio

Data & contracts#

• Reads: GET /v1/admin/isis/suspicious-activity (SUSPICIOUS_ENDPOINT) on mount — screened transactions + aggregate + baselineAvgAmount
• Writes: POST /v1/admin/isis/suspicious-activity — screen a transaction
• Realtime: None
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders()
• Auth: admin-scoped fail-closed (401/403 → unauthorized state); route direct access is hard-blocked by the Studio Isis boundary, while the localhost-only Isis lane E2E bypass still requires a signed-in Studio shell session before rendering the client workspace
• Component sources:
  • apps/oshun/web/src/components/studio/StudioIsisSuspiciousActivityDetectionWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioIsisSuspiciousActivityDetectionRouteMap.ts

Cross-references#

• Studio overview: ../../studio-overview.md
• Parent aggregator: studio-isis-anomaly-detection.md
• Sibling routes:
  • studio-isis-account-protection.md
  • studio-isis-creator-monetization.md

E2E coverage#

• apps/oshun/web/e2e/studio-isis-suspicious-activity-detection.spec.ts drives the real Next shell plus real local BFF. It proves the direct boundary hard-block, anonymous redirect, live seeded list, route map, quick actions, exact chargeback predictor output (txn-high p=0.485 medium, txn-low p=0.1 low), pending submit lockout, duplicate handling, client validation, list and screen malformed/offline failures, non-admin unauthorized state, direct BFF auth/schema gates, and mobile touch/containment.
• apps/oshun/bff/src/__tests__/admin-isis-suspicious-activity-route.test.ts keeps the BFF route contract covered at service level.
• apps/oshun/web/src/components/__tests__/StudioIsisSuspiciousActivityDetectionWorkspace.integration.test.tsx covers the workspace render/fetch integration with a schema-valid response.

Open questions / known gaps#

• Route-map deep routes (/scenes, /exports, /revisions, /governance) are advertised contract paths, not implemented pages
• Predictor is stateless per request — confirm where persistent per-user chargeback history is sourced in production vs. the demo baseline