diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c8c9237
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,50 @@
+# Node
+node_modules/
+dist/
+.vite/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+
+# Byte-compiled / optimized
+*.so
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+
+# macOS
+__MACOSX/
+
+# Model artifacts (large binaries)
+*.pkl
+
+# Misc
+*.bak
+*.tmp
diff --git a/Dockerfile.backend b/Dockerfile.backend
new file mode 100644
index 0000000..60a5521
--- /dev/null
+++ b/Dockerfile.backend
@@ -0,0 +1,32 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy dependency manifests
+COPY requirements.txt .
+COPY backend/requirements.txt backend/requirements.txt
+COPY earnings/earnings/requirements.txt earnings/earnings/requirements.txt
+COPY drivepulse_stress_model/requirements.txt drivepulse_stress_model/requirements.txt
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt \
+ && pip install --no-cache-dir -r backend/requirements.txt \
+ && pip install --no-cache-dir -r earnings/earnings/requirements.txt \
+ && pip install --no-cache-dir -r drivepulse_stress_model/requirements.txt
+
+# Copy source code
+COPY backend/ backend/
+COPY earnings/ earnings/
+COPY drivepulse_stress_model/ drivepulse_stress_model/
+
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8000
+
+# Match local dev layout: run from /app/backend so imports like `from utils...`
+# and `from data...` resolve the same as `cd backend && python main.py`
+WORKDIR /app/backend
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+
+
diff --git a/Dockerfile.frontend b/Dockerfile.frontend
new file mode 100644
index 0000000..7a206bf
--- /dev/null
+++ b/Dockerfile.frontend
@@ -0,0 +1,22 @@
+FROM node:20-alpine AS build
+
+WORKDIR /app
+
+COPY frontend/package*.json ./
+RUN npm ci
+
+COPY frontend/ .
+RUN npm run build
+
+FROM nginx:1.27-alpine
+
+WORKDIR /usr/share/nginx/html
+
+COPY --from=build /app/dist ./
+
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]
+
diff --git a/Procfile b/Procfile
new file mode 100644
index 0000000..0a0a6fc
--- /dev/null
+++ b/Procfile
@@ -0,0 +1 @@
+web: uvicorn backend.main:app --host 0.0.0.0 --port ${PORT:-8000}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..637ccbc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,159 @@
+# π DrivePulse
+
+Real-time driver wellness & earnings intelligence platform for ride-hailing drivers. Uses on-device sensor data (accelerometer, gyroscope, microphone) with ML models to detect stressful driving situations and forecast earnings velocity.
+
+---
+
+## Features
+
+- **Dashboard** β Daily trips, earnings, stress score, timeline
+- **Trip Detail** β Map playback, sensor charts, event detection with explainability
+- **Trends** β Weekly/monthly earnings, stress, and velocity charts
+- **Goals** β Set and track daily earnings targets
+- **Predict** β Enter sensor/earnings values β instant ML prediction *(judge-facing)*
+- **Batch Upload** β Upload CSV β run inference on multiple trips at once *(judge-facing)*
+- **Explainability** β Per-event feature contributions, confidence badges
+- **Feedback** β Thumbs up/down on detected events
+- **Auth** β Login / register with demo accounts or new profile
+
+To log **multiple trips at once**, go to the `Trips` tab and use **Import CSV**.
+
+---
+
+## Architecture
+
+```
+Driver-Pulse/
+βββ backend/ # FastAPI REST API (25 endpoints)
+β βββ main.py # Routes, middleware, Pydantic models
+β βββ data/
+β β βββ sample_data.py # Synthetic trip/route/event generator
+β β βββ batch_processor.py # Loads ML models, runs batch inference
+β β βββ trips_import.py # CSV trip import parser
+β β βββ users.py # In-memory auth store
+β β βββ config.py # Batch limits & constants
+β βββ utils/
+β βββ logging.py # Timestamped structured logging
+β
+βββ frontend/ # React 18 + Vite + Tailwind SPA
+β βββ src/
+β βββ pages/ # 8 pages: Home, Dashboard, Trips, TripDetail,
+β β # Trends, Goals, Predict, BatchUpload
+β βββ components/ # 16 reusable components
+β βββ api/client.js # Centralised API client
+β βββ utils/sanityChecks.js # Input validation helpers
+β
+βββ drivepulse_stress_model/ # Stress Detection ML pipeline
+β βββ run.py # CLI entry (--generate --calibrate --train --demo)
+β βββ src/
+β β βββ generate_data.py # Synthetic sensor window generator (3,150 samples)
+β β βββ train.py # RF classifier training + evaluation
+β β βββ inference.py # InferenceEngine with rule-based fallback
+β β βββ hal.py # Hardware Abstraction Layer (device calibration)
+β βββ model/ # Trained artifacts (rf_model.pkl, baselines, contract)
+β βββ calibration/ # Device calibration profile
+β
+βββ earnings/earnings/ # Earnings Forecasting ML pipeline
+β βββ run.py # Sequential pipeline entry
+β βββ src/
+β β βββ build_dataset.py # Merges drivers + goals + velocity + trips
+β β βββ features.py # 14-feature engineering (lags, rolling avg, rush flags)
+β β βββ augment.py # 5Γ Gaussian noise augmentation
+β β βββ train.py # RF regressor training + evaluation
+β β βββ inference.py # Batch velocity prediction
+β βββ model/ # Trained artifacts (rf_model.pkl, contract)
+β βββ data/ # Source CSVs (drivers, goals, velocity, trips)
+β
+βββ streamlit_app.py # Standalone Streamlit demo (3 tabs)
+βββ tests/data/ # Example CSVs for batch & import testing
+βββ requirements.txt # Root Python dependencies
+```
+
+```mermaid
+flowchart LR
+ browser[Browser_ReactApp] --> api[FastAPI_Backend]
+ api --> tripsStore[InMemory_Trips_+_Goals]
+ api --> stressBatch[Stress_Batch_Processor]
+ api --> earningsBatch[Earnings_Batch_Processor]
+ stressBatch --> stressModel[Stress_Model_Files]
+ earningsBatch --> earningsModel[Earnings_Model_Files]
+```
+
+---
+
+## Setup
+
+### Prerequisites
+- Python 3.9+
+- Node.js 18+
+ - Docker Desktop (for judge-friendly containerisation)
+
+### Install & Run (local dev)
+
+```bash
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Start backend (http://localhost:8000)
+cd backend && python main.py
+
+# In a new terminal β start frontend (http://localhost:5173)
+cd frontend && npm install && npm run dev
+```
+
+Open **http://localhost:5173** in your browser.
+
+---
+
+### Run with Docker
+
+With [Docker Desktop](https://www.docker.com/products/docker-desktop/) running:
+
+```bash
+# From the repo root (Driver-Pulse/)
+docker compose up --build
+```
+
+Then open:
+
+- Frontend: `http://localhost:5173`
+- Backend (direct): `http://localhost:8000/api/health`
+
+The frontend talks to the backend via `/api/*`, which is proxied by Nginx inside the `frontend` container to the `backend` container.
+
+**Judge login (demo account):**
+
+- Username: `judge@uber.com`
+- Password: `hackathon2026`
+
+---
+
+## Tech Stack
+
+| Layer | Tech |
+|-------|------|
+| Frontend | React 18, Vite, Tailwind CSS, Recharts, Leaflet |
+| Backend | FastAPI, Uvicorn |
+| ML | scikit-learn, NumPy, Pandas |
+
+---
+
+## Data Flow
+
+- **Trips & goals**: Manual entry or CSV import hit `/api/trips` or `/api/trips/import-csv`, which update an in-memory trips list. Goals (`/api/goals`) and dashboard (`/api/dashboard`) recompute current earnings, hours, and forecast from those trips.
+- **Batch stress & earnings**: Batch CSV uploads are processed by backend helpers that engineer features, call local models, and return per-row predictions plus summaries as JSON.
+
+---
+
+## Scalability & Modularity
+
+- **Backend**: FastAPI routes in `backend/main.py` delegate to small modules in `backend/data/` for trips, goals, imports, and batch processing, so swapping the in-memory store for a database or separate ML service is a local change.
+- **Frontend**: The React app uses a single API client layer (`frontend/src/api/client.js`) plus page/component separation, making it easy to plug in global state, auth, or feature flags without rewriting screens.
+- **Batch endpoints**: Batch CSV processing is stateless per request, so multiple backend instances can handle uploads in parallel behind a load balancer.
+
+---
+
+## Testing & Validation Notes
+
+- **Frontend sanity checks** β lightweight helpers in `frontend/src/utils/sanityChecks.js` validate money inputs, time ranges, and clamp goal targets.
+- **Example test files** β illustrative, non-wired tests live in `frontend/src/__tests__/` (e.g. `EarningsProgress.test.jsx`, `TripsAddTrip.test.jsx`) to show how key components and behaviours could be validated in a full test setup.
diff --git a/backend/data/__init__.py b/backend/data/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/data/batch_processor.py b/backend/data/batch_processor.py
new file mode 100644
index 0000000..3962f78
--- /dev/null
+++ b/backend/data/batch_processor.py
@@ -0,0 +1,443 @@
+"""
+DrivePulse Backend β Batch CSV processing.
+Loads trained stress + earnings models, runs inference on uploaded CSV data.
+"""
+
+import io
+import csv
+import json
+import math
+import numpy as np
+import joblib
+import pandas as pd
+from pathlib import Path
+from typing import Optional
+
+from .config import BATCH_ROW_SOFT_LIMIT
+
+ROOT = Path(__file__).resolve().parent.parent.parent # project root (Driver-Pulse/)
+
+# ββ Stress model ββββββββββββββββββββββββββββββββββββββββββββββ
+
+STRESS_MODEL_DIR = ROOT / "drivepulse_stress_model" / "model"
+
+STRESS_SITUATIONS = {
+ 0: {"name": "NORMAL", "emoji": "β ", "severity": "low"},
+ 1: {"name": "TRAFFIC_STOP", "emoji": "π¦", "severity": "low"},
+ 2: {"name": "SPEED_BREAKER", "emoji": "β οΈ", "severity": "medium"},
+ 3: {"name": "CONFLICT", "emoji": "π ", "severity": "high"},
+ 4: {"name": "ESCALATING", "emoji": "π΄", "severity": "high"},
+ 5: {"name": "ARGUMENT_ONLY", "emoji": "π£οΈ", "severity": "medium"},
+ 6: {"name": "MUSIC_OR_CALL", "emoji": "π΅", "severity": "low"},
+}
+
+NOTIFY_ON = {3, 4, 5}
+SAFETY_ON = {3, 4}
+
+_stress_clf = None
+_stress_mean = None
+_stress_std = None
+_stress_feats = None
+
+
+def _load_stress_model():
+ global _stress_clf, _stress_mean, _stress_std, _stress_feats
+ if _stress_clf is not None:
+ return True
+ try:
+ _stress_clf = joblib.load(STRESS_MODEL_DIR / "rf_model.pkl")
+ _stress_mean = np.load(STRESS_MODEL_DIR / "baseline_mean.npy")
+ _stress_std = np.load(STRESS_MODEL_DIR / "baseline_std.npy")
+ _stress_feats = json.loads(
+ (STRESS_MODEL_DIR / "feature_contract.json").read_text()
+ )["features"]
+ print(f"[batch] Stress model loaded ({len(_stress_feats)} features)")
+ return True
+ except Exception as e:
+ print(f"[batch] Stress model load failed: {e}")
+ return False
+
+
+def predict_stress_row(row: dict) -> dict:
+ """Run stress prediction on a single row dict."""
+ if not _load_stress_model():
+ return _stress_fallback(row)
+
+ x = np.array(
+ [float(row.get(f, 0.0)) for f in _stress_feats], dtype=np.float32
+ ).reshape(1, -1)
+ xn = (x - _stress_mean) / _stress_std
+ pred = int(_stress_clf.predict(xn)[0])
+ proba = _stress_clf.predict_proba(xn)[0]
+ conf = float(proba[pred])
+
+ if conf < 0.50:
+ pred, conf = 0, conf
+
+ sit = STRESS_SITUATIONS[pred]
+ conf_label = "high" if conf >= 0.75 else ("medium" if conf >= 0.50 else "low")
+
+ # Top 3 feature importance (simple absolute deviation approach)
+ deviations = []
+ for i, f in enumerate(_stress_feats):
+ val = float(row.get(f, 0.0))
+ mean_val = float(_stress_mean[i]) if i < len(_stress_mean) else 0
+ std_val = float(_stress_std[i]) if i < len(_stress_std) else 1
+ z = abs((val - mean_val) / max(std_val, 1e-6))
+ deviations.append({"feature": f, "z_score": round(z, 3), "value": round(val, 3)})
+ deviations.sort(key=lambda d: d["z_score"], reverse=True)
+ top3 = deviations[:3]
+
+ return {
+ "situation_id": pred,
+ "situation_name": sit["name"],
+ "emoji": sit["emoji"],
+ "severity": sit["severity"],
+ "confidence": round(conf, 3),
+ "confidence_level": conf_label,
+ "should_notify": pred in NOTIFY_ON and conf_label != "low",
+ "is_safety_critical": pred in SAFETY_ON and conf_label == "high",
+ "top_features": top3,
+ "all_probabilities": {
+ STRESS_SITUATIONS[i]["name"]: round(float(proba[i]), 4)
+ for i in range(len(proba))
+ },
+ }
+
+
+def _stress_fallback(row: dict) -> dict:
+ """Rule-based fallback when model files are missing."""
+ motion = float(row.get("motion_p95", 0))
+ audio = float(row.get("audio_db_p90", 50))
+ speed = float(row.get("speed_mean", 30))
+ lead = float(row.get("audio_leads_motion", 0))
+
+ if motion > 3.5 and audio > 80:
+ pred, conf = (4, 0.60) if lead < -5 else (3, 0.65)
+ elif motion > 3.5 and speed < 20:
+ pred, conf = 2, 0.70
+ elif motion > 3.5:
+ pred, conf = 1, 0.65
+ elif audio > 80:
+ pred, conf = 5, 0.60
+ else:
+ pred, conf = 0, 0.90
+
+ sit = STRESS_SITUATIONS[pred]
+ return {
+ "situation_id": pred,
+ "situation_name": sit["name"],
+ "emoji": sit["emoji"],
+ "severity": sit["severity"],
+ "confidence": round(conf, 3),
+ "confidence_level": "medium",
+ "should_notify": pred in NOTIFY_ON,
+ "is_safety_critical": pred in SAFETY_ON,
+ "top_features": [],
+ "all_probabilities": {},
+ }
+
+
+# ββ Earnings model ββββββββββββββββββββββββββββββββββββββββββββ
+
+EARNINGS_MODEL_DIR = ROOT / "earnings" / "earnings" / "model"
+
+EARNINGS_FEATURES = [
+ "elapsed_hours", "current_velocity", "velocity_delta",
+ "trips_completed", "trip_rate", "hour_of_day",
+ "is_morning_rush", "is_lunch_rush",
+ "velocity_last_1", "velocity_last_2", "velocity_last_3",
+ "rolling_velocity_3", "rolling_velocity_5", "goal_pressure",
+]
+
+_earnings_clf = None
+
+
+def _load_earnings_model():
+ global _earnings_clf
+ if _earnings_clf is not None:
+ return True
+ try:
+ _earnings_clf = joblib.load(EARNINGS_MODEL_DIR / "rf_model.pkl")
+ print(f"[batch] Earnings model loaded")
+ return True
+ except Exception as e:
+ print(f"[batch] Earnings model load failed: {e}")
+ return False
+
+
+def predict_earnings_row(row: dict) -> dict:
+ """Run earnings prediction on a single row dict."""
+ if not _load_earnings_model():
+ return {"predicted_velocity": None, "error": "Model not loaded"}
+
+ x = np.array(
+ [float(row.get(f, 0.0)) for f in EARNINGS_FEATURES], dtype=np.float32
+ ).reshape(1, -1)
+ predicted = float(_earnings_clf.predict(x)[0])
+ predicted = max(0, round(predicted, 2))
+
+ target_velocity = float(row.get("target_velocity", 200))
+ current_velocity = float(row.get("current_velocity", 0))
+ target_earnings = float(row.get("target_earnings", 1800))
+ current_earnings = float(row.get("cumulative_earnings", 0))
+ elapsed = float(row.get("elapsed_hours", 0))
+ remaining_earnings = max(0, target_earnings - current_earnings)
+
+ if predicted > 0:
+ hours_needed = remaining_earnings / predicted
+ else:
+ hours_needed = None
+
+ if predicted >= target_velocity * 1.1:
+ forecast = "ahead"
+ elif predicted >= target_velocity * 0.9:
+ forecast = "on_track"
+ else:
+ forecast = "at_risk"
+
+ return {
+ "predicted_velocity": round(predicted, 2),
+ "target_velocity": target_velocity,
+ "current_velocity": current_velocity,
+ "forecast_status": forecast,
+ "remaining_earnings": round(remaining_earnings, 2),
+ "hours_to_target": round(hours_needed, 2) if hours_needed else None,
+ "pct_target": round(min(100, (current_earnings / max(target_earnings, 1)) * 100), 1),
+ }
+
+
+# ββ Feature engineering for earnings (from raw trip CSV) ββββββ
+
+def engineer_earnings_features(df: pd.DataFrame) -> pd.DataFrame:
+ """
+ Takes a raw trip-level DataFrame and engineers the 14 features
+ needed for the earnings model. Columns expected:
+ driver_id, timestamp, cumulative_earnings, elapsed_hours,
+ current_velocity, target_velocity, velocity_delta,
+ trips_completed, target_earnings
+ """
+ df = df.copy()
+
+ # Parse timestamp β hour info
+ if "timestamp" in df.columns:
+ ts = pd.to_datetime(df["timestamp"], errors="coerce")
+ df["hour_of_day"] = ts.dt.hour.fillna(12).astype(int)
+ elif "hour_of_day" not in df.columns:
+ df["hour_of_day"] = 12
+
+ df["is_morning_rush"] = df["hour_of_day"].between(7, 9).astype(int)
+ df["is_lunch_rush"] = df["hour_of_day"].between(12, 14).astype(int)
+
+ # trip_rate
+ df["elapsed_hours"] = pd.to_numeric(df.get("elapsed_hours", 1), errors="coerce").fillna(1)
+ df["trips_completed"] = pd.to_numeric(df.get("trips_completed", 0), errors="coerce").fillna(0)
+ df["trip_rate"] = df["trips_completed"] / df["elapsed_hours"].replace(0, 1)
+
+ # Velocity lags + rolling
+ df["current_velocity"] = pd.to_numeric(df.get("current_velocity", 0), errors="coerce").fillna(0).clip(0, 600)
+ df["velocity_delta"] = pd.to_numeric(df.get("velocity_delta", 0), errors="coerce").fillna(0)
+ df["target_velocity"] = pd.to_numeric(df.get("target_velocity", 200), errors="coerce").fillna(200)
+
+ df = df.sort_values(["driver_id", "hour_of_day"] if "driver_id" in df.columns else ["hour_of_day"])
+ grp = "driver_id" if "driver_id" in df.columns else None
+
+ if grp:
+ df["velocity_last_1"] = df.groupby(grp)["current_velocity"].shift(1)
+ df["velocity_last_2"] = df.groupby(grp)["current_velocity"].shift(2)
+ df["velocity_last_3"] = df.groupby(grp)["current_velocity"].shift(3)
+ df["rolling_velocity_3"] = df.groupby(grp)["current_velocity"].transform(
+ lambda s: s.rolling(3, min_periods=1).mean()
+ )
+ df["rolling_velocity_5"] = df.groupby(grp)["current_velocity"].transform(
+ lambda s: s.rolling(5, min_periods=1).mean()
+ )
+ else:
+ df["velocity_last_1"] = df["current_velocity"].shift(1)
+ df["velocity_last_2"] = df["current_velocity"].shift(2)
+ df["velocity_last_3"] = df["current_velocity"].shift(3)
+ df["rolling_velocity_3"] = df["current_velocity"].rolling(3, min_periods=1).mean()
+ df["rolling_velocity_5"] = df["current_velocity"].rolling(5, min_periods=1).mean()
+
+ df["goal_pressure"] = df["target_velocity"] - df["current_velocity"]
+
+ # Fill NaNs from shifting
+ df = df.bfill().ffill().fillna(0)
+
+ return df
+
+
+# ββ Batch processing ββββββββββββββββββββββββββββββββββββββββββ
+
+def process_stress_csv(csv_content: str) -> dict:
+ """Process a CSV of sensor windows. Returns per-row predictions + summary."""
+ _load_stress_model()
+
+ reader = csv.DictReader(io.StringIO(csv_content))
+ rows = list(reader)
+
+ if not rows:
+ return {"error": "CSV is empty", "results": [], "summary": {}}
+
+ row_count = len(rows)
+ row_limit_warning = None
+ if BATCH_ROW_SOFT_LIMIT and row_count > BATCH_ROW_SOFT_LIMIT:
+ row_limit_warning = (
+ f"Processed {row_count} rows; consider chunking to {BATCH_ROW_SOFT_LIMIT} rows per upload for large workloads."
+ )
+ results = []
+ severity_counts = {"low": 0, "medium": 0, "high": 0}
+ situation_counts = {}
+
+ for i, row in enumerate(rows):
+ # Add constant features
+ row["motion_std"] = 0.3
+ row["z_dev_max"] = 0.5
+ row["spikes_above3"] = 0
+ row["spikes_above5"] = 0
+ row["audio_class_max"] = 2.0
+ row["audio_class_mean"] = 1.0
+ row["sustained_max"] = 10.0
+ row["sustained_sum"] = 50.0
+ row["cadence_var_max"] = 0.6
+ row["audio_leads_motion"] = 0.0
+ row["audio_onset_sec"] = 0.0
+ row["brake_t_sec"] = 0.0
+ row["is_low_speed"] = 0
+ row["both_elevated"] = 0
+ row["audio_only"] = 0
+ pred = predict_stress_row(row)
+ pred["row_index"] = i
+ # Carry through any extra columns (trip_id, timestamp, etc.)
+ for k in ("trip_id", "window_id", "timestamp", "start_time", "driver_id"):
+ if k in row:
+ pred[k] = row[k]
+
+ results.append(pred)
+ severity_counts[pred["severity"]] = severity_counts.get(pred["severity"], 0) + 1
+ situation_counts[pred["situation_name"]] = situation_counts.get(pred["situation_name"], 0) + 1
+
+ total = len(results)
+ avg_confidence = round(sum(r["confidence"] for r in results) / total, 3)
+ notify_count = sum(1 for r in results if r["should_notify"])
+ safety_count = sum(1 for r in results if r["is_safety_critical"])
+
+ summary = {
+ "total_windows": total,
+ "severity_counts": severity_counts,
+ "situation_counts": situation_counts,
+ "avg_confidence": avg_confidence,
+ "notifications_triggered": notify_count,
+ "safety_critical_count": safety_count,
+ "stress_score": round(
+ (severity_counts.get("high", 0) * 5 + severity_counts.get("medium", 0) * 3)
+ / max(total, 1),
+ 2,
+ ),
+ }
+ if row_limit_warning:
+ summary["row_limit_warning"] = row_limit_warning
+
+ return {
+ "results": results,
+ "summary": summary,
+ }
+
+
+def process_earnings_csv(csv_content: str) -> dict:
+ """Process a CSV of earnings/trip data. Returns per-row velocity predictions + summary."""
+ _load_earnings_model()
+
+ df = pd.read_csv(io.StringIO(csv_content))
+
+ if df.empty:
+ return {"error": "CSV is empty", "results": [], "summary": {}}
+
+ row_count = len(df)
+ row_limit_warning = None
+ if BATCH_ROW_SOFT_LIMIT and row_count > BATCH_ROW_SOFT_LIMIT:
+ row_limit_warning = (
+ f"Processed {row_count} rows; consider chunking to {BATCH_ROW_SOFT_LIMIT} rows per upload for large workloads."
+ )
+
+ # Fill defaults for missing columns
+ for col, default in [
+ ("driver_id", "driver-001"),
+ ("target_velocity", 200),
+ ("velocity_delta", 0),
+ ("target_earnings", 1800),
+ ("cumulative_earnings", 0),
+ ]:
+ if col not in df.columns:
+ df[col] = default
+
+ df = engineer_earnings_features(df)
+
+ results = []
+ total_predicted = 0
+
+ for i, row in df.iterrows():
+ row_dict = row.to_dict()
+ pred = predict_earnings_row(row_dict)
+ pred["row_index"] = int(i)
+ for k in ("driver_id", "timestamp", "trip_id", "hour_of_day"):
+ if k in row_dict:
+ pred[k] = row_dict[k]
+ if isinstance(pred[k], float) and not math.isnan(pred[k]):
+ pred[k] = int(pred[k]) if k == "hour_of_day" else pred[k]
+ elif isinstance(pred[k], float) and math.isnan(pred[k]):
+ pred[k] = None
+
+ pred["cumulative_earnings"] = round(float(row_dict.get("cumulative_earnings", 0)), 2)
+ pred["elapsed_hours"] = round(float(row_dict.get("elapsed_hours", 0)), 2)
+
+ results.append(pred)
+ if pred["predicted_velocity"] is not None:
+ total_predicted += pred["predicted_velocity"]
+
+ total = len(results)
+ avg_velocity = round(total_predicted / max(total, 1), 2)
+
+ forecast_counts = {"ahead": 0, "on_track": 0, "at_risk": 0}
+ for r in results:
+ forecast_counts[r.get("forecast_status", "on_track")] += 1
+
+ summary = {
+ "total_entries": total,
+ "avg_predicted_velocity": avg_velocity,
+ "forecast_counts": forecast_counts,
+ "best_velocity": max((r["predicted_velocity"] for r in results if r["predicted_velocity"]), default=0),
+ "worst_velocity": min((r["predicted_velocity"] for r in results if r["predicted_velocity"]), default=0),
+ }
+ if row_limit_warning:
+ summary["row_limit_warning"] = row_limit_warning
+
+ return {
+ "results": results,
+ "summary": summary,
+ }
+
+
+# ββ Template generators ββββββββββββββββββββββββββββββββββββββ
+
+def stress_csv_template() -> str:
+ """Return a CSV template string with headers + 2 sample rows."""
+ feats = [
+ "motion_max", "motion_mean", "motion_p95", "brake_intensity", "lateral_max",
+ "speed_mean", "speed_at_brake", "speed_drop",
+ "audio_db_max", "audio_db_mean", "audio_db_p90", "audio_db_std",
+ "cadence_var_mean", "argument_frac", "loud_frac",
+ ]
+ header = "trip_id,timestamp," + ",".join(feats)
+ row1 = "trip-001,08:15:00,1.2,0.6,1.1,0.8,0.5,35,35,5,68,62,67,4,0.1,0.15"
+ row2 = "trip-002,09:30:00,5.1,1.8,4.8,4.9,2.1,40,40,25,94,82,91,8,0.72,0.95"
+ return header + "\n" + row1 + "\n" + row2 + "\n"
+
+
+def earnings_csv_template() -> str:
+ """Return a CSV template string for earnings upload."""
+ header = "driver_id,timestamp,cumulative_earnings,elapsed_hours,current_velocity,target_velocity,velocity_delta,trips_completed,target_earnings"
+ row1 = "driver-001,08:00:00,0,0.5,0,200,0,0,1800"
+ row2 = "driver-001,09:00:00,185,1.5,185,200,-15,2,1800"
+ row3 = "driver-001,10:00:00,420,2.5,210,200,10,4,1800"
+ return header + "\n" + row1 + "\n" + row2 + "\n" + row3 + "\n"
diff --git a/backend/data/config.py b/backend/data/config.py
new file mode 100644
index 0000000..7911bef
--- /dev/null
+++ b/backend/data/config.py
@@ -0,0 +1,9 @@
+"""
+Shared configuration and limits for backend demo modules.
+Kept small and simple on purpose so it is easy to swap out in a real deployment.
+"""
+
+# Soft limit for batch CSV rows. Requests above this size are still processed,
+# but responses can include a warning so callers know to chunk work if needed.
+BATCH_ROW_SOFT_LIMIT = 5000
+
diff --git a/backend/data/sample_data.py b/backend/data/sample_data.py
new file mode 100644
index 0000000..e6e68da
--- /dev/null
+++ b/backend/data/sample_data.py
@@ -0,0 +1,535 @@
+"""
+DrivePulse Backend β Sample data generator.
+Produces realistic trips, events, signals, and driver metrics.
+"""
+
+import random
+import math
+import uuid
+from datetime import datetime, timedelta
+from typing import List, Dict, Any
+
+random.seed(42)
+
+# Canonical "today" used across demo endpoints.
+# (The frontend defaults to this date as well.)
+TODAY = datetime(2026, 3, 8)
+TODAY_STR = TODAY.strftime("%Y-%m-%d")
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SITUATIONS = {
+ 0: {"name": "NORMAL", "emoji": "β ", "severity": "low"},
+ 1: {"name": "TRAFFIC_STOP", "emoji": "π¦", "severity": "low"},
+ 2: {"name": "SPEED_BREAKER", "emoji": "β οΈ", "severity": "medium"},
+ 3: {"name": "CONFLICT", "emoji": "π ", "severity": "high"},
+ 4: {"name": "ESCALATING", "emoji": "π΄", "severity": "high"},
+ 5: {"name": "ARGUMENT_ONLY", "emoji": "π£οΈ", "severity": "medium"},
+ 6: {"name": "MUSIC_OR_CALL", "emoji": "π΅", "severity": "low"},
+}
+
+STRESS_TIPS = [
+ {"id": 1, "title": "Deep Breathing", "text": "Try 4-7-8 breathing: inhale 4s, hold 7s, exhale 8s. Helps reduce cortisol instantly.", "cta": "Try now"},
+ {"id": 2, "title": "Pull Over Briefly", "text": "If safe, stop for 2 minutes. A short pause resets your stress response.", "cta": "Find safe spot"},
+ {"id": 3, "title": "Adjust Temperature", "text": "Lower the AC by 2Β°. Cooler air helps reduce tension and improve alertness.", "cta": "Got it"},
+ {"id": 4, "title": "Play Calming Audio", "text": "Switch to lo-fi or nature sounds. Reduces heart rate within 3 minutes.", "cta": "Open music"},
+ {"id": 5, "title": "Stretch at Next Stop", "text": "Roll your shoulders and stretch your neck at the next red light or stop.", "cta": "Remind me"},
+ {"id": 6, "title": "Hydrate", "text": "Dehydration increases stress hormones. Take a sip of water.", "cta": "Thanks"},
+ {"id": 7, "title": "Positive Self-Talk", "text": "Remind yourself: 'This moment will pass. I'm doing well today.'", "cta": "Noted"},
+ {"id": 8, "title": "Micro-break", "text": "After this trip, take a 5-minute walk. It clears mental fatigue.", "cta": "Schedule break"},
+]
+
+# Bangalore area coordinates for route generation
+BANGALORE_CENTER = (12.9716, 77.5946)
+ROUTE_ANCHORS = [
+ [(12.9716, 77.5946), (12.9780, 77.6050), (12.9850, 77.6150), (12.9900, 77.6200)],
+ [(12.9350, 77.6140), (12.9400, 77.6050), (12.9500, 77.5970), (12.9600, 77.5900)],
+ [(12.9600, 77.5700), (12.9550, 77.5800), (12.9500, 77.5900), (12.9450, 77.6000)],
+ [(12.9800, 77.5500), (12.9750, 77.5600), (12.9700, 77.5750), (12.9716, 77.5946)],
+ [(12.9200, 77.6200), (12.9300, 77.6100), (12.9400, 77.5950), (12.9500, 77.5850)],
+ [(12.9900, 77.5800), (12.9850, 77.5900), (12.9800, 77.6000), (12.9750, 77.6100)],
+]
+
+
+def _interp_route(anchors: list, n_points: int = 60) -> list:
+ """Interpolate between anchor points to create a smooth route."""
+ route = []
+ segs = len(anchors) - 1
+ pts_per_seg = max(n_points // segs, 2)
+ for i in range(segs):
+ for j in range(pts_per_seg):
+ t = j / pts_per_seg
+ lat = anchors[i][0] + t * (anchors[i + 1][0] - anchors[i][0]) + random.gauss(0, 0.0002)
+ lng = anchors[i][1] + t * (anchors[i + 1][1] - anchors[i][1]) + random.gauss(0, 0.0002)
+ route.append([round(lat, 6), round(lng, 6)])
+ route.append(list(anchors[-1]))
+ return route
+
+
+def _gen_signals(duration_min: int, events: list) -> Dict[str, list]:
+ """Generate time-series signals: speed, accel_magnitude, audio_db."""
+ n = duration_min * 6 # one sample every 10s
+ ts = list(range(0, duration_min * 60, 10))
+ speed = []
+ accel = []
+ audio = []
+
+ base_speed = random.uniform(20, 45)
+ for i in range(n):
+ t_sec = ts[i] if i < len(ts) else i * 10
+ # Base speed with traffic variation
+ s = base_speed + 10 * math.sin(2 * math.pi * i / n) + random.gauss(0, 3)
+ a = abs(random.gauss(1.0, 0.3))
+ d = random.gauss(55, 5)
+
+ # Inject spikes near events
+ for ev in events:
+ ev_sec = ev["offset_sec"]
+ if abs(t_sec - ev_sec) < 30:
+ proximity = 1 - abs(t_sec - ev_sec) / 30
+ if ev["label"] in ("CONFLICT", "ESCALATING", "ARGUMENT_ONLY"):
+ d += 20 * proximity
+ a += 1.5 * proximity
+ elif ev["label"] == "SPEED_BREAKER":
+ a += 3 * proximity
+ s = max(5, s - 15 * proximity)
+ elif ev["label"] == "TRAFFIC_STOP":
+ s = max(0, s - s * proximity)
+
+ speed.append(round(max(0, s), 1))
+ accel.append(round(max(0, a), 2))
+ audio.append(round(max(30, min(100, d)), 1))
+
+ return {"timestamps": ts[:n], "speed": speed, "accel_magnitude": accel, "audio_db": audio}
+
+
+def _gen_events(duration_min: int, stress_level: str) -> list:
+ """Generate random events for a trip based on stress level."""
+ if stress_level == "low":
+ n_events = random.randint(0, 2)
+ pool = [0, 1, 6]
+ elif stress_level == "medium":
+ n_events = random.randint(2, 4)
+ pool = [0, 1, 2, 5, 6]
+ else:
+ n_events = random.randint(3, 6)
+ pool = [1, 2, 3, 4, 5]
+
+ events = []
+ used_offsets = set()
+ for _ in range(n_events):
+ sit_id = random.choice(pool)
+ sit = SITUATIONS[sit_id]
+ offset = random.randint(60, (duration_min - 1) * 60)
+ while any(abs(offset - u) < 30 for u in used_offsets):
+ offset = random.randint(60, (duration_min - 1) * 60)
+ used_offsets.add(offset)
+
+ confidence = round(random.uniform(0.55, 0.98), 2)
+ conf_level = "high" if confidence > 0.85 else ("medium" if confidence > 0.65 else "low")
+
+ # Feature contributions (SHAP-like)
+ all_contribs = [
+ {"feature": "accel_magnitude", "direction": "β", "contribution": round(random.uniform(0.05, 0.35), 3)},
+ {"feature": "audio_db_max", "direction": "β", "contribution": round(random.uniform(0.03, 0.30), 3)},
+ {"feature": "speed_drop", "direction": "β", "contribution": round(random.uniform(0.02, 0.25), 3)},
+ {"feature": "brake_intensity", "direction": "β", "contribution": round(random.uniform(0.01, 0.20), 3)},
+ {"feature": "lateral_max", "direction": "β", "contribution": round(random.uniform(0.01, 0.15), 3)},
+ {"feature": "sustained_max", "direction": "β" if sit_id in (3, 4, 5) else "β", "contribution": round(random.uniform(0.01, 0.18), 3)},
+ {"feature": "cadence_var_mean", "direction": "β" if sit_id in (3, 4) else "β", "contribution": round(random.uniform(0.005, 0.10), 3)},
+ ]
+ all_contribs.sort(key=lambda x: x["contribution"], reverse=True)
+ top3 = all_contribs[:3]
+
+ model_inputs = {
+ "motion_max": round(random.uniform(1, 8), 2),
+ "audio_db_max": round(random.uniform(50, 95), 1),
+ "speed_mean": round(random.uniform(5, 50), 1),
+ "brake_intensity": round(random.uniform(0, 5), 2),
+ "lateral_max": round(random.uniform(0.2, 3), 2),
+ }
+
+ events.append({
+ "id": str(uuid.uuid4())[:8],
+ "offset_sec": offset,
+ "timestamp": None, # filled later
+ "label": sit["name"],
+ "emoji": sit["emoji"],
+ "severity": sit["severity"],
+ "situation_id": sit_id,
+ "confidence": confidence,
+ "confidence_level": conf_level,
+ "explain": {
+ "model_inputs": model_inputs,
+ "top_features": top3,
+ "summary": f"Detected {sit['name'].lower().replace('_', ' ')} β primary driver: {top3[0]['feature']} {top3[0]['direction']}"
+ },
+ "feedback": None,
+ })
+
+ events.sort(key=lambda e: e["offset_sec"])
+ return events
+
+
+def _gen_trip(trip_idx: int, day: datetime, hour: int) -> Dict[str, Any]:
+ """Generate a single trip."""
+ stress_options = ["low", "low", "medium", "medium", "high"]
+ stress_level = random.choice(stress_options)
+
+ duration_min = random.randint(12, 55)
+ start_time = day.replace(hour=hour, minute=random.randint(0, 59), second=0)
+ end_time = start_time + timedelta(minutes=duration_min)
+
+ route_anchors = random.choice(ROUTE_ANCHORS)
+ route = _interp_route(route_anchors, n_points=max(30, duration_min))
+
+ distance_km = round(random.uniform(3, 25), 1)
+ base_fare = 30 + distance_km * 12 + duration_min * 2
+ surge = round(random.choice([1.0, 1.0, 1.0, 1.2, 1.5, 1.8, 2.0]), 1)
+ fare = round(base_fare * surge, 0)
+
+ events = _gen_events(duration_min, stress_level)
+ stress_score = 0
+ for ev in events:
+ w = {"low": 1, "medium": 3, "high": 5}.get(ev["severity"], 1)
+ stress_score += w * ev["confidence"]
+ stress_score = round(min(10, stress_score), 1)
+
+ # Fill event timestamps
+ for ev in events:
+ ev["timestamp"] = (start_time + timedelta(seconds=ev["offset_sec"])).isoformat()
+
+ signals = _gen_signals(duration_min, events)
+
+ # Place event markers on route
+ for ev in events:
+ frac = ev["offset_sec"] / (duration_min * 60)
+ idx = min(int(frac * len(route)), len(route) - 1)
+ ev["location"] = route[idx]
+
+ trip_id = f"trip-{trip_idx:03d}"
+ return {
+ "id": trip_id,
+ "date": day.strftime("%Y-%m-%d"),
+ "start_time": start_time.isoformat(),
+ "end_time": end_time.isoformat(),
+ "duration_min": duration_min,
+ "distance_km": distance_km,
+ "fare": fare,
+ "surge_multiplier": surge,
+ "stress_score": stress_score,
+ "stress_level": stress_level,
+ "events_count": len(events),
+ "events": events,
+ "route": route,
+ "pickup": route[0],
+ "dropoff": route[-1],
+ "signals": signals,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Public generators
+# ---------------------------------------------------------------------------
+
+def generate_trips(today: datetime = None) -> List[Dict]:
+ """Generate ~8-10 trips for today and ~8-10 for yesterday."""
+ if today is None:
+ today = datetime(2026, 3, 8)
+ yesterday = today - timedelta(days=1)
+
+ trips = []
+ idx = 1
+
+ for day, label in [(today, "today"), (yesterday, "yesterday")]:
+ n_trips = random.randint(7, 10)
+ hours = sorted(random.sample(range(6, 23), n_trips))
+ for h in hours:
+ trips.append(_gen_trip(idx, day, h))
+ idx += 1
+
+ return trips
+
+
+def generate_driver_profile() -> Dict:
+ return {
+ "id": "driver-001",
+ "name": "Ravi Kumar",
+ "city": "Bangalore",
+ "rating": 4.82,
+ "experience_months": 18,
+ "avg_hours_per_day": 10,
+ "avg_earnings_per_hour": 185,
+ "shift_preference": "morning",
+ }
+
+
+def generate_goals() -> Dict:
+ return {
+ "daily_target": 1800,
+ "current_earnings": 1230,
+ "target_hours": 10,
+ "current_hours": 6.5,
+ "trips_completed": 8,
+ "forecast_status": "on_track",
+ "goal_probability": 0.78,
+ "required_velocity": 220,
+ "current_velocity": 189,
+ }
+
+
+def build_dashboard(trips: List[Dict], goals: Dict) -> Dict:
+ """Build dashboard summary from trips and goals."""
+ today_trips = [t for t in trips if t["date"] == TODAY_STR]
+
+ total_earnings = sum(t["fare"] for t in today_trips)
+ total_hours = round(sum(t["duration_min"] for t in today_trips) / 60, 1)
+ stress_events = sum(1 for t in today_trips for e in t["events"] if e["severity"] in ("medium", "high"))
+ high_stress_count = sum(1 for t in today_trips for e in t["events"] if e["severity"] == "high")
+ pct_target = round(min(100, (total_earnings / goals["daily_target"]) * 100), 1) if goals["daily_target"] else 0
+
+ return {
+ "date": TODAY_STR,
+ "total_trips": len(today_trips),
+ "total_hours": total_hours,
+ "total_earnings": total_earnings,
+ "stress_events": stress_events,
+ "high_stress_events": high_stress_count,
+ "pct_target_achieved": pct_target,
+ "avg_stress_score": round(sum(t["stress_score"] for t in today_trips) / max(len(today_trips), 1), 1),
+ "earnings_velocity": goals["current_velocity"],
+ }
+
+
+def build_weekly_metrics(trips: List[Dict]) -> Dict:
+ """Build aggregated metrics for trends page."""
+ today = TODAY
+ days = []
+ for i in range(6, -1, -1):
+ day = today - timedelta(days=i)
+ day_str = day.strftime("%Y-%m-%d")
+ day_label = day.strftime("%a")
+ day_trips = [t for t in trips if t["date"] == day_str]
+
+ # For days without data, simulate
+ if not day_trips:
+ n = random.randint(5, 10)
+ earnings = round(random.uniform(1200, 2200), 0)
+ hours = round(random.uniform(6, 11), 1)
+ stress = round(random.uniform(2, 6), 1)
+ stress_events = random.randint(2, 8)
+ else:
+ n = len(day_trips)
+ earnings = sum(t["fare"] for t in day_trips)
+ hours = round(sum(t["duration_min"] for t in day_trips) / 60, 1)
+ stress = round(sum(t["stress_score"] for t in day_trips) / n, 1)
+ stress_events = sum(1 for t in day_trips for e in t["events"] if e["severity"] in ("medium", "high"))
+
+ days.append({
+ "date": day_str,
+ "day": day_label,
+ "trips": n,
+ "earnings": earnings,
+ "hours": hours,
+ "avg_stress": stress,
+ "stress_events": stress_events,
+ "velocity": round(earnings / max(hours, 1), 0),
+ })
+
+ return {
+ "range": "7d",
+ "days": days,
+ "summary": {
+ "avg_daily_earnings": round(sum(d["earnings"] for d in days) / 7, 0),
+ "avg_daily_trips": round(sum(d["trips"] for d in days) / 7, 1),
+ "avg_stress": round(sum(d["avg_stress"] for d in days) / 7, 1),
+ "total_earnings": sum(d["earnings"] for d in days),
+ "total_trips": sum(d["trips"] for d in days),
+ "best_day": max(days, key=lambda d: d["earnings"])["day"],
+ },
+ }
+
+
+def build_monthly_metrics() -> Dict:
+ """Build 30-day metric trend."""
+ today = TODAY
+ days = []
+ for i in range(29, -1, -1):
+ day = today - timedelta(days=i)
+ n = random.randint(5, 12)
+ earnings = round(random.uniform(1000, 2500), 0)
+ hours = round(random.uniform(5, 12), 1)
+ days.append({
+ "date": day.strftime("%Y-%m-%d"),
+ "day": day.strftime("%d %b"),
+ "trips": n,
+ "earnings": earnings,
+ "hours": hours,
+ "avg_stress": round(random.uniform(1.5, 7), 1),
+ "stress_events": random.randint(0, 10),
+ "velocity": round(earnings / max(hours, 1), 0),
+ })
+ return {
+ "range": "30d",
+ "days": days,
+ "summary": {
+ "avg_daily_earnings": round(sum(d["earnings"] for d in days) / 30, 0),
+ "avg_daily_trips": round(sum(d["trips"] for d in days) / 30, 1),
+ "avg_stress": round(sum(d["avg_stress"] for d in days) / 30, 1),
+ "total_earnings": sum(d["earnings"] for d in days),
+ "total_trips": sum(d["trips"] for d in days),
+ },
+ }
+
+
+# ---------------------------------------------------------------------------
+# Singleton data store
+# ---------------------------------------------------------------------------
+
+_TRIPS = None
+_PROFILE = None
+_GOALS = None
+
+
+def get_trips():
+ global _TRIPS
+ if _TRIPS is None:
+ _TRIPS = generate_trips()
+ return _TRIPS
+
+
+def create_user_trip(
+ *,
+ date: str,
+ start_time_iso: str,
+ end_time_iso: str,
+ duration_min: int,
+ distance_km: float,
+ fare: float,
+ stress_score: float = 0.0,
+):
+ """Create a minimal, UI-compatible trip for manual entry/import flows."""
+ # Keep detail page working by providing empty events + synthetic route/signals.
+ events = []
+ route_anchors = ROUTE_ANCHORS[0]
+ route = _interp_route(route_anchors, n_points=max(30, duration_min))
+ signals = _gen_signals(duration_min, events)
+
+ stress_score = float(stress_score or 0.0)
+ # Derive stress_level for existing UI (dots/filters).
+ if stress_score <= 3:
+ stress_level = "low"
+ elif stress_score <= 6:
+ stress_level = "medium"
+ else:
+ stress_level = "high"
+
+ return {
+ "id": f"user-{str(uuid.uuid4())[:8]}",
+ "date": date,
+ "start_time": start_time_iso,
+ "end_time": end_time_iso,
+ "duration_min": int(duration_min),
+ "distance_km": float(distance_km),
+ "fare": float(fare),
+ "surge_multiplier": 1.0,
+ "stress_score": round(min(10.0, max(0.0, stress_score)), 1),
+ "stress_level": stress_level,
+ "events_count": 0,
+ "events": events,
+ "route": route,
+ "pickup": route[0] if route else None,
+ "dropoff": route[-1] if route else None,
+ "signals": signals,
+ }
+
+
+def add_trip(trip: Dict[str, Any]) -> Dict[str, Any]:
+ trips = get_trips()
+ trips.insert(0, trip)
+ return trip
+
+
+def get_profile():
+ global _PROFILE
+ if _PROFILE is None:
+ _PROFILE = generate_driver_profile()
+ return _PROFILE
+
+
+def get_goals():
+ global _GOALS
+ if _GOALS is None:
+ _GOALS = generate_goals()
+ # Always derive "current" metrics from trips so UI stays consistent after add/import.
+ goals = _GOALS
+ trips = get_trips()
+ today_trips = [t for t in trips if t.get("date") == TODAY_STR]
+ current_earnings = round(sum(float(t.get("fare", 0) or 0) for t in today_trips), 2)
+ current_hours = round(sum(float(t.get("duration_min", 0) or 0) for t in today_trips) / 60, 2)
+ trips_completed = len(today_trips)
+ current_velocity = round(current_earnings / current_hours, 0) if current_hours > 0 else 0
+
+ goals["current_earnings"] = current_earnings
+ goals["current_hours"] = current_hours
+ goals["trips_completed"] = trips_completed
+ goals["current_velocity"] = current_velocity
+
+ _recompute_goal_derivatives(goals)
+ _GOALS = goals
+ return goals
+
+
+def set_goal_target(target: float):
+ global _GOALS
+ goals = get_goals()
+ goals["daily_target"] = float(target)
+
+ _recompute_goal_derivatives(goals)
+
+ _GOALS = goals
+ return _GOALS
+
+
+def _recompute_goal_derivatives(goals: Dict[str, Any]) -> None:
+ """
+ Keep all goal-derived fields (remaining earnings/hours, required velocity,
+ probability and forecast status) in one place so they stay consistent
+ between get_goals() and set_goal_target().
+ """
+ remaining_earnings = max(0, float(goals.get("daily_target") or 0) - float(goals.get("current_earnings") or 0))
+ remaining_hours = max(0.1, float(goals.get("target_hours") or 0) - float(goals.get("current_hours") or 0))
+ goals["required_velocity"] = round(remaining_earnings / remaining_hours, 0) if goals.get("daily_target") else 0
+ goals["remaining_earnings"] = round(remaining_earnings, 2)
+ goals["remaining_hours"] = round(
+ max(0.0, float(goals.get("target_hours") or 0) - float(goals.get("current_hours") or 0)),
+ 2,
+ )
+ current_velocity = float(goals.get("current_velocity") or 0)
+ goals["hours_to_target"] = round(remaining_earnings / current_velocity, 2) if current_velocity > 0 else None
+
+ velocity_ratio = goals["current_velocity"] / max(goals["required_velocity"], 1)
+ time_ratio = goals["current_hours"] / max(goals["target_hours"], 0.1)
+
+ if velocity_ratio >= 1.2:
+ prob = 0.95
+ elif velocity_ratio >= 1.0:
+ prob = 0.75
+ elif velocity_ratio >= 0.8:
+ prob = 0.55
+ else:
+ prob = 0.25
+
+ if time_ratio > 0.8:
+ prob *= 0.8
+
+ goals["goal_probability"] = round(min(0.99, max(0.01, prob)), 2)
+
+ if goals["current_velocity"] >= goals["required_velocity"] * 1.1:
+ goals["forecast_status"] = "ahead"
+ elif goals["current_velocity"] >= goals["required_velocity"] * 0.9:
+ goals["forecast_status"] = "on_track"
+ else:
+ goals["forecast_status"] = "at_risk"
diff --git a/backend/data/trips_import.py b/backend/data/trips_import.py
new file mode 100644
index 0000000..b6b280d
--- /dev/null
+++ b/backend/data/trips_import.py
@@ -0,0 +1,112 @@
+import csv
+from datetime import datetime
+from typing import Dict, Any, List, Optional, Tuple
+
+from .sample_data import create_user_trip, add_trip
+
+
+REQUIRED_COLUMNS = ["date", "start_time", "end_time", "distance_km", "fare"]
+OPTIONAL_COLUMNS = ["stress_score"]
+
+
+def trips_csv_template() -> str:
+ header = REQUIRED_COLUMNS + OPTIONAL_COLUMNS
+ example_rows = [
+ {
+ "date": "2026-03-08",
+ "start_time": "09:15",
+ "end_time": "09:45",
+ "distance_km": "8.2",
+ "fare": "310",
+ "stress_score": "2.5",
+ },
+ {
+ "date": "2026-03-08",
+ "start_time": "18:05",
+ "end_time": "18:40",
+ "distance_km": "11.6",
+ "fare": "520",
+ "stress_score": "6.3",
+ },
+ ]
+ lines = [",".join(header)]
+ for r in example_rows:
+ lines.append(",".join(str(r.get(k, "")) for k in header))
+ return "\n".join(lines) + "\n"
+
+
+def _parse_dt(date: str, dt_or_hhmm: str) -> datetime:
+ s = (dt_or_hhmm or "").strip()
+ if "T" in s:
+ return datetime.fromisoformat(s)
+ hh, mm = s.split(":")
+ return datetime.fromisoformat(f"{date}T{int(hh):02d}:{int(mm):02d}:00")
+
+
+def import_trips_csv(csv_content: str) -> Dict[str, Any]:
+ """
+ Parse a Trips CSV and append trips to the in-memory store.
+ Returns summary + per-row results (created trip IDs or errors).
+ """
+ reader = csv.DictReader(csv_content.splitlines())
+ if not reader.fieldnames:
+ return {"error": "CSV missing header row"}
+
+ missing = [c for c in REQUIRED_COLUMNS if c not in reader.fieldnames]
+ if missing:
+ return {"error": f"Missing required columns: {', '.join(missing)}"}
+
+ results: List[Dict[str, Any]] = []
+ created: List[Dict[str, Any]] = []
+
+ for idx, row in enumerate(reader):
+ try:
+ date = (row.get("date") or "").strip()
+ if not date:
+ raise ValueError("date is required")
+
+ start_dt = _parse_dt(date, row.get("start_time"))
+ end_dt = _parse_dt(date, row.get("end_time"))
+ if end_dt <= start_dt:
+ raise ValueError("end_time must be after start_time")
+
+ duration_min = int(round((end_dt - start_dt).total_seconds() / 60))
+ if duration_min <= 0:
+ raise ValueError("duration must be at least 1 minute")
+
+ distance_km = float(row.get("distance_km"))
+ fare = float(row.get("fare"))
+
+ stress_score_raw = (row.get("stress_score") or "").strip()
+ if stress_score_raw == "":
+ stress_score = 0.0
+ else:
+ stress_score = float(stress_score_raw)
+ if stress_score < 0 or stress_score > 10:
+ raise ValueError("stress_score must be between 0 and 10")
+
+ trip = create_user_trip(
+ date=date,
+ start_time_iso=start_dt.isoformat(),
+ end_time_iso=end_dt.isoformat(),
+ duration_min=duration_min,
+ distance_km=distance_km,
+ fare=fare,
+ stress_score=stress_score,
+ )
+ add_trip(trip)
+ created.append(trip)
+ results.append({"row_index": idx, "status": "created", "trip_id": trip["id"]})
+ except Exception as e:
+ results.append({"row_index": idx, "status": "error", "error": str(e)})
+
+ return {
+ "summary": {
+ "total_rows": len(results),
+ "created": sum(1 for r in results if r["status"] == "created"),
+ "errors": sum(1 for r in results if r["status"] == "error"),
+ },
+ "results": results,
+ "created_trips": created,
+ }
+
diff --git a/backend/data/users.py b/backend/data/users.py
new file mode 100644
index 0000000..f6eaac2
--- /dev/null
+++ b/backend/data/users.py
@@ -0,0 +1,146 @@
+"""
+DrivePulse Backend β User authentication and driver profiles.
+Manages login, registration, and driver data.
+"""
+
+import json
+from datetime import datetime
+from typing import Optional, Dict
+
+# In-memory user store (in production, use a real database)
+_USERS = {
+ "alex.kumar": {
+ "driver_id": "DRV001",
+ "password": "password123", # In production, use bcrypt
+ "name": "Alex Kumar",
+ "email": "alex.kumar@example.com",
+ "phone": "+91 9876543210",
+ "city": "Mumbai",
+ "vehicle_type": "Sedan",
+ "vehicle_number": "MH01AB1234",
+ "shift_preference": "morning",
+ "avg_hours_per_day": 7.5,
+ "avg_earnings_per_hour": 185,
+ "experience_months": 18,
+ "rating": 4.8,
+ "total_trips": 342,
+ "total_earnings": 48000,
+ },
+ "priya.singh": {
+ "driver_id": "DRV002",
+ "password": "password123",
+ "name": "Priya Singh",
+ "email": "priya.singh@example.com",
+ "phone": "+91 9876543211",
+ "city": "Bangalore",
+ "vehicle_type": "SUV",
+ "vehicle_number": "KA01CD5678",
+ "shift_preference": "evening",
+ "avg_hours_per_day": 8.2,
+ "avg_earnings_per_hour": 195,
+ "experience_months": 24,
+ "rating": 4.9,
+ "total_trips": 456,
+ "total_earnings": 62000,
+ },
+}
+
+
+def register_user(username: str, password: str, driver_data: dict) -> Optional[Dict]:
+ """Register a new user with driver profile."""
+ if username in _USERS:
+ return None # User already exists
+
+ user = {
+ "driver_id": driver_data.get("driver_id", f"DRV{len(_USERS) + 1000}"),
+ "password": password, # In production, use bcrypt.hashpw()
+ "name": driver_data.get("name", ""),
+ "email": driver_data.get("email", ""),
+ "phone": driver_data.get("phone", ""),
+ "city": driver_data.get("city", ""),
+ "vehicle_type": driver_data.get("vehicle_type", ""),
+ "vehicle_number": driver_data.get("vehicle_number", ""),
+ "shift_preference": driver_data.get("shift_preference", "morning"),
+ "avg_hours_per_day": driver_data.get("avg_hours_per_day", 7.0),
+ "avg_earnings_per_hour": driver_data.get("avg_earnings_per_hour", 180),
+ "experience_months": driver_data.get("experience_months", 0),
+ "rating": driver_data.get("rating", 4.5),
+ "total_trips": driver_data.get("total_trips", 0),
+ "total_earnings": driver_data.get("total_earnings", 0),
+ }
+
+ _USERS[username] = user
+ return {
+ "driver_id": user["driver_id"],
+ "name": user["name"],
+ "email": user["email"],
+ "city": user["city"],
+ "rating": user["rating"],
+ "vehicle_type": user["vehicle_type"],
+ }
+
+
+def login_user(username: str, password: str) -> Optional[Dict]:
+ """Authenticate a user and return their profile."""
+ if username not in _USERS:
+ return None
+
+ user = _USERS[username]
+
+ # Simple password check (in production, use bcrypt.checkpw())
+ if user["password"] != password:
+ return None
+
+ return {
+ "driver_id": user["driver_id"],
+ "username": username,
+ "name": user["name"],
+ "email": user["email"],
+ "phone": user["phone"],
+ "city": user["city"],
+ "vehicle_type": user["vehicle_type"],
+ "vehicle_number": user["vehicle_number"],
+ "rating": user["rating"],
+ "total_trips": user["total_trips"],
+ "total_earnings": user["total_earnings"],
+ "avg_hours_per_day": user["avg_hours_per_day"],
+ "avg_earnings_per_hour": user["avg_earnings_per_hour"],
+ "experience_months": user["experience_months"],
+ "shift_preference": user["shift_preference"],
+ }
+
+
+def get_user_profile(driver_id: str) -> Optional[Dict]:
+ """Get user profile by driver ID."""
+ for user in _USERS.values():
+ if user["driver_id"] == driver_id:
+ return {
+ "driver_id": user["driver_id"],
+ "name": user["name"],
+ "email": user["email"],
+ "phone": user["phone"],
+ "city": user["city"],
+ "vehicle_type": user["vehicle_type"],
+ "vehicle_number": user["vehicle_number"],
+ "rating": user["rating"],
+ "total_trips": user["total_trips"],
+ "total_earnings": user["total_earnings"],
+ "avg_hours_per_day": user["avg_hours_per_day"],
+ "avg_earnings_per_hour": user["avg_earnings_per_hour"],
+ "experience_months": user["experience_months"],
+ "shift_preference": user["shift_preference"],
+ }
+ return None
+
+
+def list_all_users() -> list:
+ """List all available users for demo purposes."""
+ return [
+ {
+ "username": username,
+ "name": user["name"],
+ "city": user["city"],
+ "rating": user["rating"],
+ }
+ for username, user in _USERS.items()
+ ]
diff --git a/backend/main.py b/backend/main.py
new file mode 100644
index 0000000..d264abe
--- /dev/null
+++ b/backend/main.py
@@ -0,0 +1,490 @@
+"""
+DrivePulse Backend β FastAPI application.
+Serves trip data, events, metrics, goals, and stress tips.
+"""
+
+from fastapi import FastAPI, HTTPException, Query, UploadFile, File
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import PlainTextResponse
+from pydantic import BaseModel
+from typing import Optional, List
+from datetime import datetime
+
+from utils.logging import log_info, log_warn
+
+from data.sample_data import (
+ get_trips, get_profile, get_goals, set_goal_target,
+ build_dashboard, build_weekly_metrics, build_monthly_metrics,
+ STRESS_TIPS, SITUATIONS,
+ create_user_trip, add_trip,
+)
+from data.batch_processor import (
+ process_stress_csv, process_earnings_csv,
+ stress_csv_template, earnings_csv_template,
+ predict_stress_row, predict_earnings_row,
+)
+from data.trips_import import import_trips_csv, trips_csv_template
+from data.users import (
+ login_user, register_user, get_user_profile, list_all_users,
+)
+
+app = FastAPI(title="DrivePulse API", version="1.0.0")
+
+app.add_middleware(
+ CORSMiddleware,
+ allow_origins=["*"],
+ allow_credentials=True,
+ allow_methods=["*"],
+ allow_headers=["*"],
+)
+
+# ββ Feedback storage (in-memory) ββββββββββββββββββββββββββββββββββββββββββ
+
+_feedback_store: dict = {}
+
+
+class FeedbackPayload(BaseModel):
+ label: str # "correct" | "incorrect" | "not_relevant"
+ comment: Optional[str] = None
+
+
+class GoalPayload(BaseModel):
+ daily_target: float
+
+
+class LoginPayload(BaseModel):
+ username: str
+ password: str
+
+
+class RegisterPayload(BaseModel):
+ username: str
+ password: str
+ name: str
+ email: str
+ phone: str
+ city: str
+ vehicle_type: str
+ vehicle_number: str
+ shift_preference: str = "morning"
+ avg_hours_per_day: float = 7.0
+ avg_earnings_per_hour: float = 180
+ experience_months: int = 0
+
+
+class TripCreatePayload(BaseModel):
+ date: str # YYYY-MM-DD
+ start_time: str # "HH:MM" (local) or ISO datetime
+ end_time: str # "HH:MM" (local) or ISO datetime
+ distance_km: float
+ fare: float
+ stress_score: Optional[float] = None # 0-10 (optional)
+
+
+# ββ Routes ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/health")
+def health():
+ log_info("health check")
+ return {"status": "ok", "timestamp": datetime.now().isoformat()}
+
+
+# ββ Authentication βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.post("/api/auth/login")
+def login(payload: LoginPayload):
+ """Authenticate a driver and return their profile."""
+ user = login_user(payload.username, payload.password)
+ if not user:
+ raise HTTPException(401, "Invalid username or password")
+ return user
+
+
+@app.post("/api/auth/register")
+def register(payload: RegisterPayload):
+ """Register a new driver account."""
+ driver_data = {
+ "name": payload.name,
+ "email": payload.email,
+ "phone": payload.phone,
+ "city": payload.city,
+ "vehicle_type": payload.vehicle_type,
+ "vehicle_number": payload.vehicle_number,
+ "shift_preference": payload.shift_preference,
+ "avg_hours_per_day": payload.avg_hours_per_day,
+ "avg_earnings_per_hour": payload.avg_earnings_per_hour,
+ "experience_months": payload.experience_months,
+ }
+ result = register_user(payload.username, payload.password, driver_data)
+ if not result:
+ raise HTTPException(400, "Username already exists")
+ return result
+
+
+@app.get("/api/auth/users")
+def list_users():
+ """List all available demo users."""
+ return list_all_users()
+
+
+@app.get("/api/profile")
+def profile():
+ return get_profile()
+
+
+# ββ Dashboard βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/dashboard")
+def dashboard():
+ trips = get_trips()
+ goals = get_goals()
+ return build_dashboard(trips, goals)
+
+
+# ββ Trips βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/trips/template", response_class=PlainTextResponse)
+def trips_template():
+ """Download a CSV template for trips import."""
+ return PlainTextResponse(
+ content=trips_csv_template(),
+ media_type="text/csv",
+ headers={"Content-Disposition": "attachment; filename=trips_template.csv"},
+ )
+
+
+@app.post("/api/trips")
+def create_trip(payload: TripCreatePayload):
+ """Create a single trip (manual entry) and persist in the in-memory store."""
+ try:
+ date = payload.date
+
+ def _to_iso(dt_or_hhmm: str) -> datetime:
+ s = (dt_or_hhmm or "").strip()
+ # Accept ISO datetime if provided
+ if "T" in s:
+ return datetime.fromisoformat(s)
+ # Accept HH:MM, combine with date
+ hh, mm = s.split(":")
+ return datetime.fromisoformat(f"{date}T{int(hh):02d}:{int(mm):02d}:00")
+
+ start_dt = _to_iso(payload.start_time)
+ end_dt = _to_iso(payload.end_time)
+ if end_dt <= start_dt:
+ raise HTTPException(400, "end_time must be after start_time")
+
+ duration_min = int(round((end_dt - start_dt).total_seconds() / 60))
+ if duration_min <= 0:
+ raise HTTPException(400, "Trip duration must be at least 1 minute")
+
+ stress_score = payload.stress_score
+ if stress_score is None:
+ stress_score = 0.0
+ try:
+ stress_score = float(stress_score)
+ except Exception:
+ raise HTTPException(400, "stress_score must be a number between 0 and 10")
+ if stress_score < 0 or stress_score > 10:
+ raise HTTPException(400, "stress_score must be between 0 and 10")
+
+ trip = create_user_trip(
+ date=date,
+ start_time_iso=start_dt.isoformat(),
+ end_time_iso=end_dt.isoformat(),
+ duration_min=duration_min,
+ distance_km=payload.distance_km,
+ fare=payload.fare,
+ stress_score=stress_score,
+ )
+ add_trip(trip)
+ return trip
+ except HTTPException:
+ raise
+ except Exception as e:
+ raise HTTPException(400, str(e))
+
+
+@app.get("/api/trips")
+def list_trips(
+ date: Optional[str] = Query(None, description="YYYY-MM-DD"),
+ stress: Optional[str] = Query(None, description="high | medium | low | any"),
+ earnings_min: Optional[float] = Query(None),
+ earnings_max: Optional[float] = Query(None),
+ time_of_day: Optional[str] = Query(None, description="morning|afternoon|evening|night"),
+ duration_min: Optional[int] = Query(None),
+ duration_max: Optional[int] = Query(None),
+ preset: Optional[str] = Query(None, description="high_stress|high_earnings|night|short"),
+):
+ trips = get_trips()
+
+ # Presets
+ if preset == "high_stress":
+ stress = "high"
+ elif preset == "high_earnings":
+ earnings_min = 500
+ elif preset == "night":
+ time_of_day = "night"
+ elif preset == "short":
+ duration_max = 15
+
+ if date:
+ trips = [t for t in trips if t["date"] == date]
+ if stress and stress != "any":
+ trips = [t for t in trips if t["stress_level"] == stress]
+ if earnings_min is not None:
+ trips = [t for t in trips if t["fare"] >= earnings_min]
+ if earnings_max is not None:
+ trips = [t for t in trips if t["fare"] <= earnings_max]
+ if duration_min is not None:
+ trips = [t for t in trips if t["duration_min"] >= duration_min]
+ if duration_max is not None:
+ trips = [t for t in trips if t["duration_min"] <= duration_max]
+ if time_of_day:
+ def _in_tod(t):
+ h = datetime.fromisoformat(t["start_time"]).hour
+ if time_of_day == "morning":
+ return 5 <= h < 12
+ elif time_of_day == "afternoon":
+ return 12 <= h < 17
+ elif time_of_day == "evening":
+ return 17 <= h < 21
+ elif time_of_day == "night":
+ return h >= 21 or h < 5
+ return True
+ trips = [t for t in trips if _in_tod(t)]
+
+ # Strip heavy data from list view
+ lite = []
+ for t in trips:
+ lite.append({k: v for k, v in t.items() if k not in ("signals", "route", "events")})
+ lite[-1]["events_summary"] = [
+ {"label": e["label"], "severity": e["severity"]}
+ for e in t["events"]
+ ]
+ return {"trips": lite, "count": len(lite)}
+
+
+@app.get("/api/trips/{trip_id}")
+def get_trip(trip_id: str):
+ trips = get_trips()
+ trip = next((t for t in trips if t["id"] == trip_id), None)
+ if not trip:
+ raise HTTPException(404, "Trip not found")
+ # Attach feedback if any
+ for ev in trip["events"]:
+ ev["feedback"] = _feedback_store.get(ev["id"])
+ return trip
+
+
+@app.get("/api/sample-trip")
+def sample_trip():
+ """Return a feature-rich sample trip for judges / quick start."""
+ trips = get_trips()
+ # Pick the trip with the most events
+ best = max(trips, key=lambda t: len(t["events"]))
+ return best
+
+
+# ββ Events & Feedback βββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/trips/{trip_id}/events")
+def trip_events(trip_id: str):
+ trips = get_trips()
+ trip = next((t for t in trips if t["id"] == trip_id), None)
+ if not trip:
+ raise HTTPException(404, "Trip not found")
+ events = trip["events"]
+ for ev in events:
+ ev["feedback"] = _feedback_store.get(ev["id"])
+ return {"trip_id": trip_id, "events": events}
+
+
+@app.post("/api/events/{event_id}/feedback")
+def post_feedback(event_id: str, payload: FeedbackPayload):
+ _feedback_store[event_id] = {"label": payload.label, "comment": payload.comment}
+ return {"status": "ok", "event_id": event_id, "feedback": _feedback_store[event_id]}
+
+
+# ββ Goals βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/goals")
+def goals():
+ return get_goals()
+
+
+@app.post("/api/goals")
+def update_goal(payload: GoalPayload):
+ return set_goal_target(payload.daily_target)
+
+
+# ββ Metrics / Trends ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/metrics")
+def metrics(range: str = Query("7d", description="7d | 30d")):
+ if range == "30d":
+ return build_monthly_metrics()
+ return build_weekly_metrics(get_trips())
+
+
+# ββ Stress Tips βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/tips")
+def tips(severity: Optional[str] = Query(None)):
+ import random as _r
+ selected = _r.sample(STRESS_TIPS, min(3, len(STRESS_TIPS)))
+ return {"tips": selected}
+
+
+# ββ Situations reference ββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.get("/api/situations")
+def situations():
+ return SITUATIONS
+
+
+# ββ Batch CSV Upload ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+@app.post("/api/batch/stress")
+async def batch_stress(file: UploadFile = File(...)):
+ """Upload a CSV of sensor windows β get stress predictions for all rows."""
+ content = (await file.read()).decode("utf-8")
+ if not content.strip():
+ raise HTTPException(400, "Empty file")
+ result = process_stress_csv(content)
+ if "error" in result and result["error"]:
+ raise HTTPException(400, result["error"])
+ return result
+
+
+@app.post("/api/batch/earnings")
+async def batch_earnings(file: UploadFile = File(...)):
+ """Upload a CSV of trip/earnings data β get velocity predictions for all rows."""
+ content = (await file.read()).decode("utf-8")
+ if not content.strip():
+ raise HTTPException(400, "Empty file")
+ result = process_earnings_csv(content)
+ if "error" in result and result["error"]:
+ raise HTTPException(400, result["error"])
+ return result
+
+
+@app.get("/api/batch/template/stress", response_class=PlainTextResponse)
+def stress_template():
+ """Download a CSV template for stress batch upload."""
+ return PlainTextResponse(
+ content=stress_csv_template(),
+ media_type="text/csv",
+ headers={"Content-Disposition": "attachment; filename=stress_template.csv"},
+ )
+
+
+@app.get("/api/batch/template/earnings", response_class=PlainTextResponse)
+def earnings_template():
+ """Download a CSV template for earnings batch upload."""
+ return PlainTextResponse(
+ content=earnings_csv_template(),
+ media_type="text/csv",
+ headers={"Content-Disposition": "attachment; filename=earnings_template.csv"},
+ )
+
+
+# ββ Trips CSV Import (creates trips) βββββββββββββββββββββββββββββββββββββββ
+
+@app.post("/api/trips/import-csv")
+async def import_trips(file: UploadFile = File(...)):
+ """Upload a Trips CSV and persist rows as trips (in-memory)."""
+ content = (await file.read()).decode("utf-8")
+ if not content.strip():
+ raise HTTPException(400, "Empty file")
+ result = import_trips_csv(content)
+ if "error" in result and result["error"]:
+ raise HTTPException(400, result["error"])
+ return result
+
+
+# ββ Single-row manual prediction ββββββββββββββββββββββββββββββββββββββββββ
+
+@app.post("/api/predict/stress")
+def predict_stress(payload: dict):
+ """Submit a single row of sensor features β get stress prediction."""
+ try:
+ # Add constant features
+ payload.setdefault("motion_std", 0.3)
+ payload.setdefault("z_dev_max", 0.5)
+ payload.setdefault("spikes_above3", 0)
+ payload.setdefault("spikes_above5", 0)
+ payload.setdefault("audio_class_max", 2.0)
+ payload.setdefault("audio_class_mean", 1.0)
+ payload.setdefault("sustained_max", 10.0)
+ payload.setdefault("sustained_sum", 50.0)
+ payload.setdefault("cadence_var_max", 0.6)
+ payload.setdefault("audio_leads_motion", 0.0)
+ payload.setdefault("audio_onset_sec", 0.0)
+ payload.setdefault("brake_t_sec", 0.0)
+ payload.setdefault("is_low_speed", 0)
+ payload.setdefault("both_elevated", 0)
+ payload.setdefault("audio_only", 0)
+ result = predict_stress_row(payload)
+ return result
+ except Exception as e:
+ raise HTTPException(400, str(e))
+
+
+@app.post("/api/predict/earnings")
+def predict_earnings(payload: dict):
+ """Submit a single row of earnings features β get velocity prediction."""
+ try:
+ result = predict_earnings_row(payload)
+ return result
+ except Exception as e:
+ raise HTTPException(400, str(e))
+
+
+@app.get("/api/features/stress")
+def stress_features():
+ """Return the list of stress model input features with defaults."""
+ features = [
+ {"name": "motion_max", "label": "Motion Max (g)", "default": 1.5, "group": "Motion"},
+ {"name": "motion_mean", "label": "Motion Mean (g)", "default": 0.8, "group": "Motion"},
+ {"name": "motion_p95", "label": "Motion P95 (g)", "default": 1.2, "group": "Motion"},
+ {"name": "brake_intensity", "label": "Brake Intensity", "default": 0.5, "group": "Motion"},
+ {"name": "lateral_max", "label": "Lateral Max (g)", "default": 0.8, "group": "Motion"},
+ {"name": "speed_mean", "label": "Speed Mean (km/h)", "default": 30.0, "group": "Speed"},
+ {"name": "speed_at_brake", "label": "Speed at Brake (km/h)", "default": 25.0, "group": "Speed"},
+ {"name": "speed_drop", "label": "Speed Drop (km/h)", "default": 5.0, "group": "Speed"},
+ {"name": "audio_db_max", "label": "Audio dB Max", "default": 65.0, "group": "Audio"},
+ {"name": "audio_db_mean", "label": "Audio dB Mean", "default": 55.0, "group": "Audio"},
+ {"name": "audio_db_p90", "label": "Audio dB P90", "default": 62.0, "group": "Audio"},
+ {"name": "audio_db_std", "label": "Audio dB Std", "default": 5.0, "group": "Audio"},
+ {"name": "cadence_var_mean", "label": "Cadence Var Mean", "default": 0.3, "group": "Voice"},
+ {"name": "argument_frac", "label": "Argument Fraction", "default": 0.0, "group": "Voice"},
+ {"name": "loud_frac", "label": "Loud Fraction", "default": 0.1, "group": "Voice"},
+ ]
+ return {"features": features, "total": len(features)}
+
+
+@app.get("/api/features/earnings")
+def earnings_features():
+ """Return the list of earnings model input features with defaults."""
+ features = [
+ {"name": "avg_earnings_per_hour", "label": "Avg Earnings/hr (βΉ)", "default": 250.0, "group": "Earnings"},
+ {"name": "experience_months", "label": "Experience (months)", "default": 12, "group": "Driver"},
+ {"name": "rating", "label": "Rating (1-5)", "default": 4.5, "group": "Driver"},
+ {"name": "target_earnings", "label": "Target Earnings (βΉ)", "default": 2000.0, "group": "Earnings"},
+ {"name": "remaining_earnings", "label": "Remaining Earnings (βΉ)", "default": 1200.0, "group": "Earnings"},
+ {"name": "remaining_hours", "label": "Remaining Hours", "default": 5.0, "group": "Time"},
+ {"name": "required_velocity", "label": "Required Velocity (βΉ/hr)", "default": 240.0, "group": "Earnings"},
+ {"name": "trips_completed", "label": "Trips Completed", "default": 5, "group": "Trip"},
+ {"name": "trip_rate", "label": "Trip Rate (trips/hr)", "default": 2.0, "group": "Trip"},
+ {"name": "hour_of_day", "label": "Hour of Day (0-23)", "default": 14, "group": "Time"},
+ {"name": "is_morning_rush", "label": "Morning Rush (0/1)", "default": 0, "group": "Time"},
+ {"name": "is_lunch_rush", "label": "Lunch Rush (0/1)", "default": 0, "group": "Time"},
+ {"name": "is_evening_rush", "label": "Evening Rush (0/1)", "default": 0, "group": "Time"},
+ {"name": "current_velocity", "label": "Current Velocity (βΉ/hr)", "default": 200.0, "group": "Earnings"},
+ ]
+ return {"features": features, "total": len(features)}
+
+
+if __name__ == "__main__":
+ import uvicorn
+ uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
diff --git a/backend/requirements.txt b/backend/requirements.txt
new file mode 100644
index 0000000..fcec658
--- /dev/null
+++ b/backend/requirements.txt
@@ -0,0 +1,9 @@
+fastapi>=0.104
+uvicorn>=0.24
+pydantic>=2.0
+python-multipart>=0.0.6
+numpy>=1.24.0
+pandas>=2.0.0
+scikit-learn>=1.3.0
+joblib>=1.3.0
+python-dateutil>=2.8
\ No newline at end of file
diff --git a/backend/utils/logging.py b/backend/utils/logging.py
new file mode 100644
index 0000000..661fdb5
--- /dev/null
+++ b/backend/utils/logging.py
@@ -0,0 +1,20 @@
+"""
+Very small logging helper for the demo backend.
+In a real deployment this is where structured logging or APM hooks would live.
+"""
+
+from datetime import datetime
+
+
+def _ts() -> str:
+ return datetime.now().isoformat()
+
+
+def log_info(message: str) -> None:
+ print(f"[info] { _ts() } {message}")
+
+
+def log_warn(message: str) -> None:
+ print(f"[warn] { _ts() } {message}")
+
+
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..9a0de62
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,21 @@
+version: "3.9"
+
+services:
+ backend:
+ build:
+ context: .
+ dockerfile: Dockerfile.backend
+ container_name: drivepulse-backend
+ ports:
+ - "8000:8000"
+
+ frontend:
+ build:
+ context: .
+ dockerfile: Dockerfile.frontend
+ container_name: drivepulse-frontend
+ ports:
+ - "5173:80"
+ depends_on:
+ - backend
+
diff --git a/docs/PROGRESS_LOG.md b/docs/PROGRESS_LOG.md
new file mode 100644
index 0000000..c5631a3
--- /dev/null
+++ b/docs/PROGRESS_LOG.md
@@ -0,0 +1,27 @@
+# Progress Log (Development History)
+
+A chronological log of our problem-solving process and major iterations.
+
+
+---
+
+**Mar 4:** Project kickoff. Team discussion on requirements, user persona, and value proposition. Decided on stress + earnings as dual focus.
+
+**Mar 5:** Finalized tech stack (FastAPI, React, scikit-learn). Planned architecture and repo structure. Set up the project repository and initial folder structure.
+
+**Mar 6:** Backend development: implemented API skeleton (trips, goals, dashboard), created synthetic trip data generator, and batch processor.
+
+**Mar 7:** Backend ML: built and trained initial stress detection (RF, HAL, Platt calibration) and earnings velocity models. Added endpoints for batch inference and CSV import.
+
+**Mar 8:** Frontend development: built dashboard, trip list, trip detail, earnings progress bar. Integrated backend APIs. Added batch upload and explainability features.
+
+**Mar 9:** Documentation: wrote design doc (HTML), architecture diagram (SVG), and progress log. Re-checked all features, tested flows, and made final edits based on feedback. Prepared for deployment.
+
+**Mar 10:** Deployment and submission: added Dockerised deployment (FastAPI + React via Nginx, `docker-compose.yml` at repo root), verified end-to-end flows in containers, and documented judge login plus Docker run instructions in all README/docs before final submission.
+
+---
+
+**Outcome:**
+Successfully built and deployed DrivePulse β a driver safety and earnings intelligence platform that transforms raw trip signals into actionable insights. The system combines real-time stress detection with earnings velocity forecasting while maintaining privacy through on-device processing. All core features (stress detection, earnings forecasting, explainability tools, batch testing, and feedback collection) were implemented as planned. Documentation, architecture diagrams, and progress logs were completed and the project was submitted on time.
+
+---
\ No newline at end of file
diff --git a/docs/architecture_explanation.html b/docs/architecture_explanation.html
new file mode 100644
index 0000000..88a0b2d
--- /dev/null
+++ b/docs/architecture_explanation.html
@@ -0,0 +1,327 @@
+
+
+
+
+
+ DrivePulse β System Architecture
+
+
+
+
+
+
+
π DrivePulse
+
System Architecture
+
UBER SHE++ HACKATHON 2026
+
MerinRishitLavisha
+
+
+
+
+
+
+
+
+
01 Architecture Diagram
+
End-to-end data flow: sensors β on-device processing β server β driver insights β feedback loop.
+
+
+
+
Right-click β "Save image as" or screenshot this diagram to export as PNG.
+
+
+
+
+
+
02 Architecture Explanation
+
Design decisions and engineering trade-offs.
+
+
Real-Time vs. Post-Trip Processing
+
+
Stress detection β real-time, on-device. RF classifier runs per 30s window in <1ms. Driver gets alerts instantly, no network needed.
+
Earnings prediction β on-device per trip. Velocity forecasting runs locally after each trip completes.
+
Aggregation β server-side. Dashboard summaries, trends, and goal tracking are computed on the server where full trip history is available.
+
Why this split? A driver in danger can't wait for a network round-trip. Safety alerts must work in tunnels and dead zones.
+
+
+
Connectivity & Resilience
+
+
Both ML models run locally β no network required for predictions.
+
Queued sync β trip data and feedback stored locally, synced when connectivity returns.
+
Rule-based fallback β if model files are missing, threshold rules (motion >3.5g + audio >80 dB β CONFLICT) keep the app functional.
+
SPA frontend β once loaded, all navigation works offline; only API data calls need network.
+
+
+
Battery & Resource Management
+
+
Lightweight RF models β no GPU, <1ms inference, ~12 stress features (not hundreds).
+
10 Hz sampling β sufficient for brakes/road events; 10Γ less data than high-frequency approaches.
+
30s windows β model runs ~2Γ/min, not continuously.
+
dB envelope only β loudness levels, not raw audio waveforms. No FFT/spectrogram cost.
+
EMA drift correction β simple update every 10 min, not a full recalibration.
+
+
+
Privacy & Data Minimisation
+
+
No raw audio β mic input reduced to dB aggregates on-device. No recordings leave the phone.
+
No raw sensor logs β accelerometer data consumed in 30s windows, converted to statistical features, then discarded.
+
All audio classification on-device β server never receives audio data.
+
Minimal PII β username + city + experience level. No phone number, no payment data.
+
Feedback is opt-in β only event ID + boolean. No free-text harvested.
+
+
+
Key Trade-offs
+
+
Decision
Gained
Gave Up
+
On-device inference
Zero-latency alerts, offline support
Can't use large models or cross-driver patterns
+
RandomForest over DL
Lightweight, interpretable, CPU-only
Lower accuracy on complex temporal patterns
+
dB envelope over raw audio
Privacy, low CPU, no storage
No speech-to-text or fine-grained analysis
+
In-memory store over DB
Zero setup for judges
No persistence across restarts
+
Feedback collected, not looped
Simpler system
Model doesn't self-improve (yet)
+
+
+
+
+
+
+
03 Deployment & Docker
+
How a judge runs the full system in minutes.
+
+
+ Hackathon requirement: Include a working Dockerfile and docker-compose.yml
+ so a judge can run the entire stack with a single command. DrivePulse ships two services
+ (FastAPI backend + React frontend) wired together behind Nginx.
+
+
+
Containers
+
+
Backend container: Python 3.11 + FastAPI. Runs uvicorn main:app inside the backend/ folder so imports like from utils... and from data... match local dev. Exposes 8000 with all /api/* routes.
+
Frontend container: Builds the React SPA with Node + Vite, then serves the static dist/ bundle via Nginx on port 80. Nginx proxies any request to /api/ to the backend service.
+
Compose orchestration:docker-compose.yml in the repo root builds both images, creates a shared network, and publishes:
+
+
http://localhost:5173 β frontend (Nginx)
+
http://localhost:8000 β backend (FastAPI, e.g. /api/health)
+
+
+
+
+
Judge Runbook
+
+
Prerequisite: Install Docker Desktop and ensure it is running.
+
Clone repo:git clone ... && cd Driver-Pulse
+
One command:
+ docker compose up --build from the repo root (Driver-Pulse/).
+
Open app: visit http://localhost:5173 in the browser
+ (no manual dependency installation required).
+
+
+
+ Judge credentials: we provide a pre-populated demo account.
+ Username: judge@uber.com Β· Password: hackathon2026.
+
Who it's for, what it does, and why it's built this way.
+
+
User Persona
+
+ Full-time ride-hailing driver in an Indian metro city (Bangalore in our demo).
+ Drives 8β10 hours daily. Cares about two things: staying safe on chaotic roads and
+ hitting a daily earnings target. Not tech-savvy β needs information delivered at a glance,
+ not buried in charts.
+
+
+
Core Value Proposition
+
+ DrivePulse transforms raw trip signals β accelerometer, speed, audio dB β into two actionable insights:
+
+
+
Safety alerts β Detects dangerous situations (hard braking + loud cabin, escalating conflicts) in real-time and tells the driver why each event was flagged.
+
Earnings forecasting β Predicts earnings velocity (βΉ/hr), shows whether the driver is on track to hit their daily target, and estimates time-to-goal.
+
+
+
The "Glanceable" Test
+
+ A driver can't read a dense dashboard while navigating traffic. Every screen in DrivePulse is designed to pass the 2-second glance test:
+
+
+
Dashboard β 5 large summary cards at the top. Green/yellow/red colour coding. No mental math needed.
+
Today Timeline β Horizontal hour blocks colour-coded by stress. One glance = "how has my day been?"
+
Earnings Progress β Single progress bar with current βΉ/hr vs required βΉ/hr. Status: π’ ahead / π‘ on_track / π΄ at_risk.
+
Event Cards β Emoji + one-line message + confidence badge. No jargon. "π¨ Hard brake + loud cabin at the same time."
+
Stress Tips β Dismissible amber cards with actionable advice. Not data β actions.
+
+
+
+ Design principle: The driver should never have to interpret raw numbers.
+ Every metric is translated into a status (ahead / on_track / at_risk), a colour (green / yellow / red),
+ or a plain-language message. Detailed signal charts and explainability modals exist for the
+ Trip Detail page β but they're opt-in, not the default view.
+
+
+
+
+
+
02 Stress Detection Algorithm
+
Lightweight signal processing, sensor fusion, and false-positive reduction.
+
+
Pipeline
+
+
Raw Sensors10 Hz
β
+
HALDevice Norm
β
+
30s Window~12 features
β
+
Z-ScoreBaseline ΞΌ/Ο
β
+
RF Classifyβ 7 classes
β
+
Platt Calβ true prob
+
+
+
Cleaning Noisy Motion Data (HAL)
+
Phone sensors are noisy and device-dependent. Our Hardware Abstraction Layer runs a two-phase calibration:
+
+
Phase 1 β Audio baseline: 30s stationary recording. Uses 10th-percentile dB as ambient floor, computes mic gain correction (target 52 dB). Normalises mic sensitivity across phone models.
+
Phase 2 β Road baseline: First 2 min of driving at >20 km/h. Detects gravity axis, computes accelerometer scale factor, and measures road vibration baseline. Subtracts road noise from real events.
+
Drift correction: EMA update (Ξ±=0.15) every 10 min adjusts audio floor and vibration baseline.
+
+
After HAL, accelerometer output = net motion above road vibration, audio = net cabin noise above ambient. Device-agnostic.
+
+
Interpreting Audio Intensity
+
Audio features are acoustic aggregates only β no raw audio stored (privacy by design). Key features per 30s window:
+
+
audio_db_mean / p90 β overall cabin loudness
+
sustained_max β duration of sustained loud episodes
audio_leads_motion β did audio spike before a hard brake? (escalation signal)
+
+
The insight: arguments have irregular cadence + sustained loudness, while music has regular cadence + steady levels. These two features alone separate ARGUMENT from MUSIC_OR_CALL well.
+
+
Multi-Sensor Fusion
+
Dangerous situations are rarely single-sensor. The key fusion features:
audio_leads_motion β audio spikes >5s before hard brake β ESCALATING (argument β panic brake).
+
audio_only β high audio, no motion anomaly β ARGUMENT_ONLY or MUSIC_OR_CALL, not a road event.
+
+
+
Reducing False Positives
+
+
Platt calibration: Sigmoid recalibration so 85% confidence β 85% true probability. Alerts only on HIGH (β₯75%).
+
Confidence gating: If top-class confidence <50%, system defaults to NORMAL β no alert.
+
Class weighting: CONFLICT and ESCALATING weighted 3Γ during training (favour recall on dangerous events); Platt step corrects the resulting overconfidence.
+
Rule-based fallback: If model files are missing, simple thresholds (motion >3.5g + audio >80 dB β CONFLICT) ensure the app never crashes.
+
+
+
Output
+
Per 30s window: situation class (7 classes), calibrated confidence (HIGH / MEDIUM / LOW), top feature deviations (for explainability), safety flag, <1ms inference on CPU.
+
+
+
+
+
03 Earnings Velocity Algorithm
+
Current speed, forecasting, and cold-start handling.
+
+
Pipeline
+
+
Driver Statetrips, hours, βΉ
β
+
Feature Eng14 features
β
+
RF Regress300 trees
β
+
βΉ/hr + Status+ probability
+
+
+
Current Earnings Speed
+
Earnings velocity = cumulative earnings Γ· elapsed hours (βΉ/hr). Required velocity = remaining earnings Γ· remaining hours. The gap between the two gives an instant "am I on track?" signal.
Time to goal: remaining earnings Γ· predicted velocity
+
+
+
Handling Cold Start
+
First 15 min of a shift β no velocity lags, unstable trip rate, no rolling averages.
+
+
Backfill: Missing lags set to current velocity (conservative β assumes no trend until proven).
+
Rolling windows: Use whatever data points are available, then backfill remaining NaN.
+
Goal pressure as anchor: Even with zero history, the model knows target vs current velocity β a strong directional signal from reading one.
+
Static profile features:avg_earnings_per_hour, experience_months, rating are available from registration and provide baseline expectations.
+
+
+
+ Edge case: A driver with a βΉ5,000 target and 2 hours left sees required = βΉ2,500/hr β clearly unreachable.
+ The model predicts honestly; the dashboard shows π΄ at_risk. We don't hide bad news.
+
How we designed the repo and Docker setup so judges can run DrivePulse in a few minutes.
+
+
Zero-setup runtime
+
To avoid asking judges to install Python, Node, or ML libraries locally, we ship a fully containerised stack:
+
+
Backend:Dockerfile.backend builds a Python 3.11 image, installs all ML and FastAPI dependencies from the repo's requirements.txt files, and starts uvicorn main:app from backend/.
+
Frontend:Dockerfile.frontend builds the React + Vite SPA, then serves it via Nginx, which also proxies /api/* to the backend service.
+
Compose:docker-compose.yml at the root orchestrates both services and exposes:
+
+
http://localhost:5173 β Nginx + React SPA
+
http://localhost:8000/api/health β backend health check
+
+
+
+
+
Judge run instructions
+
We repeat the exact steps (as required by the hackathon) in the root README.md and docs:
+
+
Install Docker Desktop and ensure it is running.
+
git clone ... && cd Driver-Pulse
+
From the repo root run: docker compose up --build
+
Visit http://localhost:5173 to use the app; optional backend health at http://localhost:8000/api/health.
+
+
+
+ Judge login: we provide a pre-configured demo account so judges land in a realistic dashboard immediately.
+ Username: judge@uber.com Β· Password: hackathon2026.
+
+
+
+ This approach satisfies the hackathon's Docker criterion: a working Dockerfile and docker-compose.yml
+ at the repo root, with a single docker compose up --build command to start the entire application.
+
+ {mode === 'stress'
+ ? 'These are 30-second window features from accelerometer, gyroscope, and microphone sensors. Defaults represent a calm driving scenario.'
+ : 'Enter your current shift stats. The model predicts your earnings velocity (βΉ/hr) and whether you\'re on track to hit your target.'
+ }
+