# zaidbharde/foresight architecture

> Architecture diagram of the GitHub repository zaidbharde/foresight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zaidbharde/foresight
- Repository: https://github.com/zaidbharde/foresight

## Overview

#### 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: [`backend/services/prediction_service.py`](https://github.com/zaidbharde/foresight/blob/main/backend/services/prediction_service.py) (Prediction orchestration), [`backend/api/predict.py`](https://github.com/zaidbharde/foresight/blob/main/backend/api/predict.py) (Prediction endpoint), [`Foresight/app/src/main/java/com/example/foresight/PaymentViewModel.kt`](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/PaymentViewModel.kt) (Payment state), [`Foresight/app/src/main/java/com/example/foresight/screens/PaymentScreen.kt`](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/screens/PaymentScreen.kt) (Payment and review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android client"]
  node_android_entry["Compose app host<br/>Kotlin/Compose<br/>[MainActivity.kt]"]
  node_android_navigation["Payment navigation<br/>Compose navigation<br/>[Navigation.kt]"]
  node_payment_screens["Payment and review<br/>Compose screens<br/>[PaymentScreen.kt]"]
  node_payment_state["Payment state<br/>ViewModel"]
  node_input_boundaries["QR and UPI inputs<br/>Payment input<br/>[QRScannerScreen.kt]"]
  node_risk_result["Risk result<br/>Compose screen"]
  node_risk_repository["Risk repository<br/>Android repository<br/>[RiskRepository.kt]"]
  node_api_client["Backend API client<br/>Retrofit service<br/>[ApiService.kt]"]
  node_firebase_auth["Phone authentication<br/>Firebase adapter"]
end

subgraph group_backend["Serving backend"]
  node_api_entry["FastAPI application<br/>Python/FastAPI<br/>[main.py]"]
  node_predict_route["Prediction endpoint<br/>FastAPI route<br/>[predict.py]"]
  node_contracts["Transaction contracts<br/>Pydantic schemas<br/>[request.py]"]
  node_prediction_service["Prediction orchestration"]
  node_feature_builder["Feature infrastructure<br/>Feature pipeline<br/>[builder.py]"]
  node_feature_contract["Serving feature contract<br/>JSON contract"]
  node_risk_engine["Hybrid risk engine<br/>Decision engine<br/>[engine.py]"]
  node_risk_rules["Versioned fraud rules<br/>Policy JSON<br/>[risk_rules_v1.json]"]
  node_model[("Baseline model<br/>XGBoost artifact")]
end

subgraph group_demo_ml["Demo and ML work"]
  node_vision_api["VISION ON API<br/>Python demo API<br/>[app.py]"]
  node_vision_ui["VISION ON dashboard<br/>React/Vite<br/>[main.jsx]"]
  node_ml_preprocessing["Offline preprocessing<br/>ML pipeline"]
  node_ml_baselines["Model experiments<br/>ML evaluation"]
end

node_firebase{{"Firebase<br/>External identity"}}

node_android_entry -->|"hosts"| node_android_navigation
node_android_navigation -->|"routes to"| node_payment_screens
node_input_boundaries -->|"populates payment details"| node_payment_screens
node_payment_screens -->|"updates"| node_payment_state
node_payment_state -->|"requests assessment"| node_risk_repository
node_risk_repository -->|"uses"| node_api_client
node_api_client -->|"POST prediction"| node_predict_route
node_payment_state -->|"drives result state"| node_risk_result
node_firebase_auth -->|"authenticates with"| node_firebase
node_api_entry -->|"mounts"| node_predict_route
node_predict_route -->|"validates request and response"| node_contracts
node_predict_route -->|"invokes"| node_prediction_service
node_prediction_service -->|"builds features"| node_feature_builder
node_feature_builder -->|"conforms to"| node_feature_contract
node_prediction_service -->|"combines scoring and controls"| node_risk_engine
node_prediction_service -->|"scores with"| node_model
node_risk_engine -->|"evaluates"| node_risk_rules
node_vision_ui -->|"calls"| node_vision_api
node_ml_preprocessing -->|"feeds training experiments"| node_ml_baselines
node_ml_baselines -.->|"produces deployed baseline"| node_model

click node_android_entry "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/MainActivity.kt"
click node_android_navigation "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/Navigation.kt"
click node_payment_screens "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/screens/PaymentScreen.kt"
click node_payment_state "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/PaymentViewModel.kt"
click node_input_boundaries "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/screens/QRScannerScreen.kt"
click node_risk_result "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/screens/RiskResultScreen.kt"
click node_risk_repository "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/data/repository/RiskRepository.kt"
click node_api_client "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/data/network/ApiService.kt"
click node_firebase_auth "https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/data/auth/FirebaseAuthManager.kt"
click node_api_entry "https://github.com/zaidbharde/foresight/blob/main/backend/main.py"
click node_predict_route "https://github.com/zaidbharde/foresight/blob/main/backend/api/predict.py"
click node_contracts "https://github.com/zaidbharde/foresight/blob/main/backend/schemas/request.py"
click node_prediction_service "https://github.com/zaidbharde/foresight/blob/main/backend/services/prediction_service.py"
click node_feature_builder "https://github.com/zaidbharde/foresight/blob/main/backend/feature_infrastructure/builder.py"
click node_feature_contract "https://github.com/zaidbharde/foresight/blob/main/shared/contracts/feature_schema_v2.json"
click node_risk_engine "https://github.com/zaidbharde/foresight/blob/main/backend/risk_engine/engine.py"
click node_risk_rules "https://github.com/zaidbharde/foresight/blob/main/backend/config/risk_rules_v1.json"
click node_model "https://github.com/zaidbharde/foresight/blob/main/backend/models/xgboost_baseline.pkl"
click node_vision_api "https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/app.py"
click node_vision_ui "https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/frontend/src/main.jsx"
click node_ml_preprocessing "https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/step_1_preprocessing.py"
click node_ml_baselines "https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/step_2_baseline_models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android_entry,node_android_navigation,node_payment_screens,node_payment_state,node_input_boundaries,node_risk_result,node_risk_repository,node_api_client,node_firebase_auth toneBlue
class node_api_entry,node_predict_route,node_contracts,node_prediction_service,node_feature_builder,node_feature_contract,node_risk_engine,node_risk_rules,node_model toneAmber
class node_vision_api,node_vision_ui,node_ml_preprocessing,node_ml_baselines toneMint
class node_firebase toneNeutral
```

## Components

### Android client

- [Compose app host](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/MainActivity.kt): Kotlin/Compose · `Foresight/app/src/main/java/com/example/foresight/MainActivity.kt`
- [Payment navigation](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/Navigation.kt): Compose navigation · `Foresight/app/src/main/java/com/example/foresight/Navigation.kt`
- [Payment and review](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/screens/PaymentScreen.kt): Compose screens · Captures and confirms transaction context. · `Foresight/app/src/main/java/com/example/foresight/screens/PaymentScreen.kt`
- [Payment state](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/PaymentViewModel.kt): ViewModel · `Foresight/app/src/main/java/com/example/foresight/PaymentViewModel.kt`
- [QR and UPI inputs](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/screens/QRScannerScreen.kt): Payment input · `Foresight/app/src/main/java/com/example/foresight/screens/QRScannerScreen.kt`
- [Risk result](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/screens/RiskResultScreen.kt): Compose screen · Presents risk tier, action, and reasons. · `Foresight/app/src/main/java/com/example/foresight/screens/RiskResultScreen.kt`
- [Risk repository](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/data/repository/RiskRepository.kt): Android repository · `Foresight/app/src/main/java/com/example/foresight/data/repository/RiskRepository.kt`
- [Backend API client](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/data/network/ApiService.kt): Retrofit service · `Foresight/app/src/main/java/com/example/foresight/data/network/ApiService.kt`
- [Phone authentication](https://github.com/zaidbharde/foresight/blob/main/Foresight/app/src/main/java/com/example/foresight/data/auth/FirebaseAuthManager.kt): Firebase adapter · `Foresight/app/src/main/java/com/example/foresight/data/auth/FirebaseAuthManager.kt`

### Serving backend

- [FastAPI application](https://github.com/zaidbharde/foresight/blob/main/backend/main.py): Python/FastAPI · `backend/main.py`
- [Prediction endpoint](https://github.com/zaidbharde/foresight/blob/main/backend/api/predict.py): FastAPI route · `backend/api/predict.py`
- [Transaction contracts](https://github.com/zaidbharde/foresight/blob/main/backend/schemas/request.py): Pydantic schemas · Defines typed prediction inputs and risk outputs. · `backend/schemas/request.py`
- [Prediction orchestration](https://github.com/zaidbharde/foresight/blob/main/backend/services/prediction_service.py): Service · Builds features and combines ML with fraud controls. · `backend/services/prediction_service.py`
- [Feature infrastructure](https://github.com/zaidbharde/foresight/blob/main/backend/feature_infrastructure/builder.py): Feature pipeline · Builds and verifies model-compatible transaction features. · `backend/feature_infrastructure/builder.py`
- [Serving feature contract](https://github.com/zaidbharde/foresight/blob/main/shared/contracts/feature_schema_v2.json): JSON contract · Serving-time authority for feature definitions. · `shared/contracts/feature_schema_v2.json`
- [Hybrid risk engine](https://github.com/zaidbharde/foresight/blob/main/backend/risk_engine/engine.py): Decision engine · Evaluates rules and assigns risk tier and action. · `backend/risk_engine/engine.py`
- [Versioned fraud rules](https://github.com/zaidbharde/foresight/blob/main/backend/config/risk_rules_v1.json): Policy JSON · `backend/config/risk_rules_v1.json`
- [Baseline model](https://github.com/zaidbharde/foresight/blob/main/backend/models/xgboost_baseline.pkl): XGBoost artifact · `backend/models/xgboost_baseline.pkl`

### Demo and ML work

- [VISION ON API](https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/app.py): Python demo API · `VISION ON/app.py`
- [VISION ON dashboard](https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/frontend/src/main.jsx): React/Vite · `VISION ON/frontend/src/main.jsx`
- [Offline preprocessing](https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/step_1_preprocessing.py): ML pipeline · `VISION ON/step_1_preprocessing.py`
- [Model experiments](https://github.com/zaidbharde/foresight/blob/main/VISION%20ON/step_2_baseline_models.py): ML evaluation · Baseline comparison, tuning, and explainability lineage. · `VISION ON/step_2_baseline_models.py`

### Other components

- **Firebase**: External identity

## Connections

- 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