How zaidbharde/foresight works
Purpose and Repository Shape
FORESIGHT is a UPI-payment fraud-prevention system: it evaluates a transaction before payment and returns a risk score, risk tier, action, and reasons. The repository contains a production-oriented Python backend, an Android Jetpack Compose client, a separate React/FastAPI demo (“VISION ON”), and offline ML/dataset materials.
Primary Serving Entry Points
• FastAPI application entry point: backend/main.py; prediction route: backend/api/predict.py.
• Android application entry point and Compose host: Foresight/app/src/main/java/com/example/foresight/MainActivity.kt; navigation graph: Foresight/app/src/main/java/com/example/foresight/Navigation.kt.
• Separate demo API/UI entry points: VISION ON/app.py and VISION ON/frontend/src/main.jsx.
• The root README’s described frontend layout does not exactly match this tree; the checked-in web client is under VISION ON/frontend.
Request Contract and Feature Boundary
The backend exposes typed transaction inputs and risk outputs through Pydantic schemas:
• backend/schemas/request.py
• backend/schemas/response.py
• shared/contracts/feature_schema_v2.json
Feature infrastructure centralizes feature construction, contract adherence, and verification before scoring. This is the key boundary between client-provided payment context and model/rules-compatible inputs:
• backend/feature_infrastructure/builder.py
• backend/feature_infrastructure/contract.py
• backend/feature_infrastructure/verification.py
Hybrid Risk Decision Pipeline
Prediction orchestration resides in backend/services/prediction_service.py. It builds/verifies features, invokes ML scoring, and combines it with deterministic fraud controls. The hybrid engine owns tiering and rule evaluation:
• backend/risk_engine/engine.py
• backend/risk_engine/rules.py
• backend/risk_engine/models.py
Rules are externally versioned in backend/config/risk_rules_v1.json, allowing policy changes—such as OTP-scam indicators or critical-risk freezes—without changing client navigation. The deployed baseline model artifact is backend/models/xgboost_baseline.pkl.
Android Payment and Safety Flow
The Android client uses Compose screens and view models to guide a transaction through payment capture, review, processing, risk presentation, and completion:
• Foresight/app/src/main/java/com/example/foresight/screens/PaymentScreen.kt
• Foresight/app/src/main/java/com/example/foresight/screens/ReviewPaymentScreen.kt
• Foresight/app/src/main/java/com/example/foresight/screens/RiskResultScreen.kt
Foresight/app/src/main/java/com/example/foresight/PaymentViewModel.kt coordinates payment state; Foresight/app/src/main/java/com/example/foresight/data/repository/RiskRepository.kt isolates backend risk calls. QR and UPI deep-link handling are separate payment-input boundaries:
• Foresight/app/src/main/java/com/example/foresight/screens/QRScannerScreen.kt
• Foresight/app/src/main/java/com/example/foresight/UpiRedirection.kt
Identity, Networking, and External Services
Firebase phone authentication is wrapped by Foresight/app/src/main/java/com/example/foresight/data/auth/FirebaseAuthManager.kt. Retrofit-based API access is defined in:
• Foresight/app/src/main/java/com/example/foresight/data/network/ApiService.kt
• Foresight/app/src/main/java/com/example/foresight/data/network/RetrofitClient.kt
Material runtimes are Python/FastAPI for backend inference, Android/Kotlin/Compose for the mobile client, and React/Vite for the demo dashboard. Firebase is the explicit external identity service; no real bank or UPI-provider integration is represented in the tree.
Offline ML and Explainability Work
The VISION ON Python scripts represent an offline experimentation/training lineage: preprocessing, baseline comparisons, imbalance tuning, and explainability analysis:
• VISION ON/step_1_preprocessing.py
• VISION ON/step_2_baseline_models.py
• VISION ON/step_4_5_explainability_optimization.py
Dataset engineering and intended feature definitions are documented in FORESIGHT-IEEE-CIS-Dataset/FeatureSchema.md and docs/FeatureSchema.md. These artifacts inform model development, while the backend’s feature contract is the serving-time authority.
Main entry points: prediction_service.py Prediction orchestration · predict.py Prediction endpoint · PaymentViewModel.kt Payment state · PaymentScreen.kt Payment and review
Components 23
Android client
- Compose app host
Foresight/app/src/main/java/com/example/foresight/MainActivity.kt - Payment navigation
Foresight/app/src/main/java/com/example/foresight/Navigation.kt - Payment and review · Captures and confirms transaction context.
Foresight/app/src/main/java/com/example/foresight/screens/PaymentScreen.kt - Payment state
Foresight/app/src/main/java/com/example/foresight/PaymentViewModel.kt - QR and UPI inputs
Foresight/app/src/main/java/com/example/foresight/screens/QRScannerScreen.kt - Risk result · Presents risk tier, action, and reasons.
Foresight/app/src/main/java/com/example/foresight/screens/RiskResultScreen.kt - Risk repository
Foresight/app/src/main/java/com/example/foresight/data/repository/RiskRepository.kt - Backend API client
Foresight/app/src/main/java/com/example/foresight/data/network/ApiService.kt - Phone authentication
Foresight/app/src/main/java/com/example/foresight/data/auth/FirebaseAuthManager.kt
Serving backend
- FastAPI application
backend/main.py - Prediction endpoint
backend/api/predict.py - Transaction contracts · Defines typed prediction inputs and risk outputs.
backend/schemas/request.py - Prediction orchestration · Builds features and combines ML with fraud controls.
backend/services/prediction_service.py - Feature infrastructure · Builds and verifies model-compatible transaction features.
backend/feature_infrastructure/builder.py - Serving feature contract · Serving-time authority for feature definitions.
shared/contracts/feature_schema_v2.json - Hybrid risk engine · Evaluates rules and assigns risk tier and action.
backend/risk_engine/engine.py - Versioned fraud rules
backend/config/risk_rules_v1.json - Baseline model
backend/models/xgboost_baseline.pkl
Demo and ML work
- VISION ON API
VISION ON/app.py - VISION ON dashboard
VISION ON/frontend/src/main.jsx - Offline preprocessing
VISION ON/step_1_preprocessing.py - Model experiments · Baseline comparison, tuning, and explainability lineage.
VISION ON/step_2_baseline_models.py
Other components
- Firebase
Connections 20
- Compose app host → Payment navigation: hosts
- Payment navigation → Payment and review: routes to
- QR and UPI inputs → Payment and review: populates payment details
- Payment and review → Payment state: updates
- Payment state → Risk repository: requests assessment
- Risk repository → Backend API client: uses
- Backend API client → Prediction endpoint: POST prediction
- Payment state → Risk result: drives result state
- Phone authentication → Firebase: authenticates with
- FastAPI application → Prediction endpoint: mounts
- Prediction endpoint → Transaction contracts: validates request and response
- Prediction endpoint → Prediction orchestration: invokes
- Prediction orchestration → Feature infrastructure: builds features
- Feature infrastructure → Serving feature contract: conforms to
- Prediction orchestration → Hybrid risk engine: combines scoring and controls
- Prediction orchestration → Baseline model: scores with
- Hybrid risk engine → Versioned fraud rules: evaluates
- VISION ON dashboard → VISION ON API: calls
- Offline preprocessing → Model experiments: feeds training experiments
- Model experiments → Baseline model: produces deployed baseline