Fraud Detection¶

Scores customer transaction behaviour and produces investigator-facing AI reports for the banking dashboard.


Primary repo	`fraud-detection-ai-backend/`
Stream siblings	`fraud-detection-ai-backend-stream/` → `ml_service`, `rule_service`, `case_management_service`
Runtime	Pub/Sub-driven FastAPI on Cloud Run + three prediction microservices
Status	IMPLEMENTED

Why it exists¶

Banks need continuous monitoring of unusual times, locations/devices/merchants, and amount/velocity patterns. This stack builds behavioural baselines, accepts ML or rule predictions, applies a fixed output contract and decision policy, and posts a structured report (AI summary included) to the dashboard.

Invariant: the LLM may explain a decision; it must not make approve / pend / block. Evidence: fraud-detection-ai-backend/docs/fraud-output-contract.md (mirrored under Reference) and src/report_team/.

Happy path¶

sequenceDiagram
  participant Caller
  participant Checks as fraud_detection_ai_backend
  participant PubSub
  participant Pred as ml_or_rule_service
  participant Dash as backend_api
  Caller->>Checks: POST /batch_check
  Checks->>PubSub: per-customer messages on stats topic
  PubSub->>Checks: /temporal_check /location_check /transaction_check
  Checks->>Checks: persist profiles or cold_start skip
  Pred->>PubSub: prediction envelope
  PubSub->>Checks: POST /report
  Checks->>Checks: validate normalize policy AI_summary
  Checks->>Dash: POST /transaction/create-report

Checks + report service¶

Evidence: src/app.py, README.md, src/config/appconfig.py, src/constant.py.

Method	Path	Trigger	Purpose	Status
GET	`/health`	HTTP	Liveness (predictions DB + data dir)	IMPLEMENTED
POST	`/batch_check`	HTTP	Publish one stats message per customer	IMPLEMENTED
POST	`/temporal_check`	Push sub `start-temporal-checks-<env>`	Time / velocity baselines	IMPLEMENTED
POST	`/location_check`	Push sub `start-location-checks-<env>`	Location / device / merchant novelty	IMPLEMENTED
POST	`/transaction_check`	Push sub `start-transaction-checks-<env>`	Amount / frequency anomalies	IMPLEMENTED
POST	`/report`	Push sub `fraud-system-report-<env>`	Contract + policy + summary → dashboard	IMPLEMENTED
POST	`/chapelhill/instruction_check`	HTTP	Deterministic instruction verification (client flow)	IMPLEMENTED — not a separate platform product

Topics: process-customer-statistics-<PYTHON_ENV>, generate-ai-report-<PYTHON_ENV> (plus DLTs from Cloud Build).

Cold start: if txn count < COLD_START_MIN_TRANSACTIONS (10), no profile is stored; rule service is expected to cover those customers. src/preprocessing/detect.py also defines warm-start at 20.

Dashboard handoff: POST {backend_api}/transaction/create-report with Authorization: ApiKey <jwt> and x-tenant-id (src/auth/auth_utils.py, src/app.py).

Stream prediction services¶

Evidence: each */src/app.py, stream README.md.

Service	Local port	Primary route	Status
`ml_service`	8080	`POST /call-and-predict`	IMPLEMENTED
`rule_service`	8081	`POST /rule_based_engine`	IMPLEMENTED
`case_management_service`	8082	`POST /case_management_rule_engine`	IMPLEMENTED

Protected routes: Authorization: ApiKey <jwt> + x-tenant-id. GET /health is open. Kill-switch env: AUTH_ENFORCEMENT_ENABLED.

ML also exposes /feedback-event, /admin/blacklist-refresh, /process-excel, /batch-send.

Limitations¶

Anomaly weights in src/constant.py must stay aligned with the ML service copy.
Output contract documents field gaps (e.g. channel on transaction events).
/chapelhill/instruction_check is client-specific; do not document Chapel Hill as its own product on this site.