Fraud API

Mental model

Most production traffic is Pub/Sub push into fraud-detection-ai-backend. Stream services expose HTTP predict APIs that the platform calls with JWT + tenant header. Report completion callbacks go to APP_BACKEND_API / backend_api.

Checks service routes

Base: Cloud Run URL for fraud-detection-ai-backend (local often :8080).

Method	Path	Body	Notes
GET	/health	—	Open
POST	/batch_check	tenant and/or customer_profile_ids	Publishes to process-customer-statistics-<env>
POST	/temporal_check	Pub/Sub envelope or ChecksPayload JSON	Baseline
POST	/location_check	same	Baseline
POST	/transaction_check	same	Baseline
POST	/report	Pub/Sub envelope or AiReportPayload	Validates contract → dashboard
POST	/chapelhill/instruction_check	instruction body	Requires x-tenant-id; optional idempotency key

Evidence: src/app.py. Prefer running /docs over copying field lists.

Report → dashboard

POST {backend_api}/transaction/create-report
Authorization: ApiKey <ai-signed-jwt>
x-tenant-id: <tenant>

Policy + evidence fields are computed in Python (src/report_team/); Gemini fills narrative summary only.

Cold start

If historical txn count < 10, check handlers return cold-start and skip profile persistence. Route those customers through rule_service.

Stream services

Service	Path	Required headers
ml_service	POST /call-and-predict	Authorization: ApiKey <jwt>, x-tenant-id
rule_service	POST /rule_based_engine	same
case_management_service	POST /case_management_rule_engine	same

Mint local JWTs with iss=software-service, aud=ai-service, signed by the backend private key matching BACKEND_PUBLIC_KEY on the AI service. See stream README “Local Auth Setup”.

Contract

Predictions consumed by /report must satisfy fraud output contract. Mixed ML+rule identity keys → AMBIGUOUS_PREDICTION_CONTRACT. Score/tier conflicts → ML_SCORE_TIER_CONFLICT.

Local smoke

cd fraud-detection-ai-backend
poetry install
# env: PYTHON_ENV, PROJECT_ID, DB_CREDENTIALS or DB_*, AI_PRIVATE_KEY, BACKEND_PUBLIC_KEY, APP_BACKEND_API, …
poetry run uvicorn src.app:app --reload --port 8080
curl -s http://localhost:8080/health

Gaps

• Static OpenAPI export for fraud is not checked into platform-docs (KYC only) — use live /openapi.json when running.
• Edge auth on Pub/Sub push URL (UNKNOWN beyond GCP push configuration in cloudbuild.yaml).