Skip to content

APP_LOGIC.md

Latest commit

 

History

History
60 lines (45 loc) · 2.84 KB

APP_LOGIC.md

File metadata and controls

60 lines (45 loc) · 2.84 KB
Raw

How the App Works: System Logic & Architecture

This document explains the internal mechanics, formulas, and data flow of the Event-Based ML Backend.

1. High-Level Workflow

The system follows a linear pipeline triggered weekly (or via API) to evaluate income loss:

  1. Ingestion: External signals (Weather, Traffic, Demand) are fetched for a region.
  2. Preprocessing: Raw user income history is converted into ML features.
  3. ML Prediction: The system predicts what a user should have earned (I_exp).
  4. Loss Detection: Compares actual income (I_act) against I_exp.
  5. Decision Engine: Validates if the loss was caused by external disruptions.
  6. Claim Trigger: Calculates and records the final payout if all conditions are met.

2. Machine Learning Strategy

We use a Layered Model Architecture to ensure accuracy across different scales.

A. Regional Models

Users in different zones (e.g., North vs. South) have different income baselines and sensitivities to weather. We train separate models per zone:

  • Baseline: regression_model_North.pkl
  • Baseline: regression_model_South.pkl

B. Personalized Adjustments

When a specific user's patterns consistently deviate from their regional average (e.g., they work more night shifts), the system can generate a Personalized Model (user_model_{id}.pkl).

  • Priority: The AI service always checks for a User Model first, then falls back to the Regional Model, and finally to a Global default.

3. The Decision Engine (Rules)

A claim isn't just about losing money; it must be validated against three factors:

The Validation Formula: Valid = T AND A AND M

  • T (Disruption): Was there a significant macro-event? (Calculated from weather/traffic scores).
  • A (Activity): Was the user actually attempting to work? (Verified via active days).
  • M (Mismatch): Is the income drop significant? (Calculated via the 30% Loss Ratio threshold).

4. Claim Calculation Formula

If a claim is valid, the amount is not just a static percentage. It uses a Dynamic Multiplier (theta):

C_final = theta * I_exp * gamma_m

Where:

  • I_exp: Expected income (from AI).
  • gamma_m: Base coverage ratio (default 80%).
  • theta: Adjusts based on disruption severity (D_s), number of previous claims (N_c), and seniority level (S_i).
    • More severe disruptions increase the payout.
    • Frequent past claims slightly reduce the multiplier to prevent fraud/over-reliance.

5. API Layer Overview

  • /users: Management of user profiles and zones.
  • /income: Tracking historical weekly earnings.
  • /predictions:
    • GET /<id>: View real-time AI expected vs actual statistics.
    • POST /run-pipeline: The administrative "Big Button" that runs the entire logic loop for all users.
  • /claims: History of auto-triggered and approved payouts.