# sanjayt2706/driverbehaviorproject architecture

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

- Interactive diagram: https://gitdiagram.com/sanjayt2706/driverbehaviorproject
- Repository: https://github.com/sanjayt2706/driverbehaviorproject

## Overview

DriverRisk is a smartphone-based driving behavior and trip-risk analysis project. The intended user workflow is to collect GPS and IMU data during a trip, retain it locally, upload/process it through the backend, and inspect trip-level risk results. The backend’s documented processing stages include cleaning, windowing, feature extraction, road geometry, and curve density; the repository also contains a separate model-training workflow. The Dashboard directory described in the README is absent from the supplied tree, and the Android home screen currently does not start recording. Some backend route and inference wiring is therefore left unspecified.

Main entry points: [`Backend/app/processing/pipeline.py`](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/pipeline.py) (Processing pipeline), [`Android/app/src/main/java/com/driverisk/app/service/TripRecordingService.kt`](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/service/TripRecordingService.kt) (Recording service), [`ML/src/step05_split_scale.py`](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step05_split_scale.py) (Split and scale), [`ML/src/step08_evaluate.py`](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step08_evaluate.py) (Evaluate models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Android collection"]
  node_home["Home UI<br/>[HomeFragment.kt]"]
  node_service["Recording service"]
  node_location["GPS collector"]
  node_imu["IMU collector<br/>[SensorCollector.kt]"]
  node_detector["Trip detector<br/>[TripDetector.kt]"]
  node_repository["Trip repository<br/>[TripRepository.kt]"]
  node_room[("Local trip store")]
end

subgraph group_backend["Backend processing"]
  node_api["Trip API<br/>[trips.py]"]
  node_pipeline["Processing pipeline<br/>[pipeline.py]"]
  node_preprocess["Clean samples<br/>[preprocessing.py]"]
  node_windows["Window samples<br/>[windowing.py]"]
  node_features["Extract features<br/>[features.py]"]
  node_geometry["Road geometry<br/>[road_geometry.py]"]
  node_curves["Curve density<br/>[curve_density.py]"]
  node_serverdb[("Backend database<br/>[database.py]")]
end

subgraph group_inference["Model inference"]
  node_predictor["Risk predictor<br/>[predictor.py]"]
  node_model["Model wrapper<br/>[model_wrapper.py]"]
  node_explainer["SHAP explainer<br/>[shap_explainer.py]"]
  node_reason["Risk explanation<br/>[reason_text.py]"]
end

subgraph group_training["Model training"]
  node_loadraw["Load raw data<br/>[step01_load_raw.py]"]
  node_cleantrain["Clean data<br/>[step02_clean.py]"]
  node_label["Label samples<br/>[step03_label.py]"]
  node_buildfeatures["Build features"]
  node_split["Split and scale"]
  node_trainrf["Train Random Forest<br/>[step06_train_rf.py]"]
  node_trainxgb["Train XGBoost"]
  node_evaluate["Evaluate models<br/>[step08_evaluate.py]"]
  node_select["Select model"]
  node_globalshap["Global SHAP"]
end

node_driver(("Driver"))
node_dataset["UAH-DriveSet"]
node_dashboard["Analytics dashboard"]

node_driver -->|"uses"| node_home
node_home -.->|"start intent"| node_service
node_service -->|"collects GPS"| node_location
node_service -->|"collects IMU"| node_imu
node_service -->|"checks speed"| node_detector
node_service -->|"persists trip"| node_repository
node_repository -->|"reads and writes"| node_room
node_api -->|"processes trip"| node_pipeline
node_pipeline -->|"cleans"| node_preprocess
node_pipeline -->|"creates windows"| node_windows
node_pipeline -->|"extracts features"| node_features
node_pipeline -->|"extracts geometry"| node_geometry
node_pipeline -->|"enriches curves"| node_curves
node_api -->|"stores trip data"| node_serverdb
node_predictor -->|"predicts with"| node_model
node_explainer -->|"formats reasons"| node_reason
node_dataset -->|"loads"| node_loadraw
node_loadraw -->|"cleans"| node_cleantrain
node_cleantrain -->|"labels"| node_label
node_label -->|"constructs features"| node_buildfeatures
node_buildfeatures -->|"splits and scales"| node_split
node_split -->|"trains"| node_trainrf
node_split -->|"trains"| node_trainxgb
node_trainrf -->|"evaluates"| node_evaluate
node_trainxgb -->|"evaluates"| node_evaluate
node_evaluate -->|"selects best"| node_select
node_select -->|"explains model"| node_globalshap
node_serverdb -.->|"visualizes results"| node_dashboard

click node_home "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/ui/home/HomeFragment.kt"
click node_service "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/service/TripRecordingService.kt"
click node_location "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/sensors/LocationCollector.kt"
click node_imu "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/sensors/SensorCollector.kt"
click node_detector "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/sensors/TripDetector.kt"
click node_repository "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/data/repository/TripRepository.kt"
click node_room "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/data/local/DriveRiskDatabase.kt"
click node_api "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/api/routes/trips.py"
click node_pipeline "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/pipeline.py"
click node_preprocess "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/preprocessing.py"
click node_windows "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/windowing.py"
click node_features "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/features.py"
click node_geometry "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/road_geometry.py"
click node_curves "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/curve_density.py"
click node_serverdb "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/database.py"
click node_predictor "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/ml/predictor.py"
click node_model "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/ml/model_wrapper.py"
click node_explainer "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/explain/shap_explainer.py"
click node_reason "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/explain/reason_text.py"
click node_loadraw "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step01_load_raw.py"
click node_cleantrain "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step02_clean.py"
click node_label "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step03_label.py"
click node_buildfeatures "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step04_build_features.py"
click node_split "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step05_split_scale.py"
click node_trainrf "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step06_train_rf.py"
click node_trainxgb "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step07_train_xgb.py"
click node_evaluate "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step08_evaluate.py"
click node_select "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step09_select_best.py"
click node_globalshap "https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step10_global_shap.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_home,node_service,node_location,node_imu,node_detector,node_repository,node_room toneBlue
class node_api,node_pipeline,node_preprocess,node_windows,node_features,node_geometry,node_curves,node_serverdb toneAmber
class node_predictor,node_model,node_explainer,node_reason toneMint
class node_loadraw,node_cleantrain,node_label,node_buildfeatures,node_split,node_trainrf,node_trainxgb,node_evaluate,node_select,node_globalshap toneRose
class node_driver,node_dataset,node_dashboard toneIndigo
```

## Components

### Android collection

- [Home UI](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/ui/home/HomeFragment.kt): `Android/app/src/main/java/com/driverisk/app/ui/home/HomeFragment.kt`
- [Recording service](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/service/TripRecordingService.kt): `Android/app/src/main/java/com/driverisk/app/service/TripRecordingService.kt`
- [GPS collector](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/sensors/LocationCollector.kt): `Android/app/src/main/java/com/driverisk/app/sensors/LocationCollector.kt`
- [IMU collector](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/sensors/SensorCollector.kt): `Android/app/src/main/java/com/driverisk/app/sensors/SensorCollector.kt`
- [Trip detector](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/sensors/TripDetector.kt): `Android/app/src/main/java/com/driverisk/app/sensors/TripDetector.kt`
- [Trip repository](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/data/repository/TripRepository.kt): `Android/app/src/main/java/com/driverisk/app/data/repository/TripRepository.kt`
- [Local trip store](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Android/app/src/main/java/com/driverisk/app/data/local/DriveRiskDatabase.kt): `Android/app/src/main/java/com/driverisk/app/data/local/DriveRiskDatabase.kt`

### Backend processing

- [Trip API](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/api/routes/trips.py): `Backend/app/api/routes/trips.py`
- [Processing pipeline](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/pipeline.py): `Backend/app/processing/pipeline.py`
- [Clean samples](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/preprocessing.py): `Backend/app/processing/preprocessing.py`
- [Window samples](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/windowing.py): `Backend/app/processing/windowing.py`
- [Extract features](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/features.py): `Backend/app/processing/features.py`
- [Road geometry](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/road_geometry.py): `Backend/app/processing/road_geometry.py`
- [Curve density](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/processing/curve_density.py): `Backend/app/processing/curve_density.py`
- [Backend database](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/database.py): `Backend/app/database.py`

### Model inference

- [Risk predictor](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/ml/predictor.py): `Backend/app/ml/predictor.py`
- [Model wrapper](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/ml/model_wrapper.py): `Backend/app/ml/model_wrapper.py`
- [SHAP explainer](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/explain/shap_explainer.py): `Backend/app/explain/shap_explainer.py`
- [Risk explanation](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/Backend/app/explain/reason_text.py): `Backend/app/explain/reason_text.py`

### Model training

- [Load raw data](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step01_load_raw.py): `ML/src/step01_load_raw.py`
- [Clean data](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step02_clean.py): `ML/src/step02_clean.py`
- [Label samples](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step03_label.py): `ML/src/step03_label.py`
- [Build features](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step04_build_features.py): `ML/src/step04_build_features.py`
- [Split and scale](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step05_split_scale.py): `ML/src/step05_split_scale.py`
- [Train Random Forest](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step06_train_rf.py): `ML/src/step06_train_rf.py`
- [Train XGBoost](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step07_train_xgb.py): `ML/src/step07_train_xgb.py`
- [Evaluate models](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step08_evaluate.py): `ML/src/step08_evaluate.py`
- [Select model](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step09_select_best.py): `ML/src/step09_select_best.py`
- [Global SHAP](https://github.com/sanjayt2706/driverbehaviorproject/blob/main/ML/src/step10_global_shap.py): `ML/src/step10_global_shap.py`

### Other components

- **Driver**
- **UAH-DriveSet**
- **Analytics dashboard**

## Connections

- Driver → Home UI: uses
- Home UI → Recording service: start intent
- Recording service → GPS collector: collects GPS
- Recording service → IMU collector: collects IMU
- Recording service → Trip detector: checks speed
- Recording service → Trip repository: persists trip
- Trip repository → Local trip store: reads and writes
- Trip API → Processing pipeline: processes trip
- Processing pipeline → Clean samples: cleans
- Processing pipeline → Window samples: creates windows
- Processing pipeline → Extract features: extracts features
- Processing pipeline → Road geometry: extracts geometry
- Processing pipeline → Curve density: enriches curves
- Trip API → Backend database: stores trip data
- Risk predictor → Model wrapper: predicts with
- SHAP explainer → Risk explanation: formats reasons
- UAH-DriveSet → Load raw data: loads
- Load raw data → Clean data: cleans
- Clean data → Label samples: labels
- Label samples → Build features: constructs features
- Build features → Split and scale: splits and scales
- Split and scale → Train Random Forest: trains
- Split and scale → Train XGBoost: trains
- Train Random Forest → Evaluate models: evaluates
- Train XGBoost → Evaluate models: evaluates
- Evaluate models → Select model: selects best
- Select model → Global SHAP: explains model
- Backend database → Analytics dashboard: visualizes results