# akashmeh/safecruise architecture

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

- Interactive diagram: https://gitdiagram.com/akashmeh/safecruise
- Repository: https://github.com/akashmeh/safecruise

## Overview

SafeCruise is a research prototype for temporal driving-risk scoring and inspection. Its implemented workflow accepts a telemetry window through the FastAPI service, derives time-windowed features, predicts risk with a persisted XGBoost model, and can return SHAP explanations; a Streamlit dashboard replays trips through the shared scoring path. A separate training workflow builds features from DriveSet data and writes model and evaluation artifacts. The README describes phone/vehicle alerts and connected-vehicle integrations, but the sampled source does not establish their implementation or wiring.

Main entry points: [`dashboard.py`](https://github.com/akashmeh/safecruise/blob/main/dashboard.py) (Streamlit dashboard), [`features.py`](https://github.com/akashmeh/safecruise/blob/main/features.py) (Risk scoring), [`train_full_model.py`](https://github.com/akashmeh/safecruise/blob/main/train_full_model.py) (Training and evaluation), [`main.py`](https://github.com/akashmeh/safecruise/blob/main/main.py) (FastAPI endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and Features"]
  node_ingest["Trip ingestion<br/>[features.py]"]
  node_dataset["Merged trip data"]
  node_engineering["Temporal features<br/>[features.py]"]
  node_scoring["Risk scoring<br/>[features.py]"]
  node_explain["SHAP explanations<br/>[features.py]"]
end

subgraph group_ml["Model Lifecycle"]
  node_training["Training and evaluation"]
  node_model["XGBoost model"]
  node_evaluation["Evaluation artifacts"]
end

subgraph group_serving["Scoring Service"]
  node_api["FastAPI endpoints<br/>[main.py]"]
end

subgraph group_inspect["Dashboard"]
  node_dashboard["Streamlit dashboard<br/>[dashboard.py]"]
end

node_driver(("Telemetry client"))
node_driveset["DriveSet trips"]

node_driveset -->|"supplies trips"| node_ingest
node_ingest -->|"builds dataset"| node_dataset
node_training -->|"loads data"| node_ingest
node_training -->|"engineers features"| node_engineering
node_training -->|"writes model"| node_model
node_training -->|"writes metrics"| node_evaluation
node_driver -->|"posts windows"| node_api
node_api -->|"scores windows"| node_scoring
node_scoring -->|"derives features"| node_engineering
node_scoring -->|"loads model"| node_model
node_scoring -->|"requests attribution"| node_explain
node_api -->|"formats impacts"| node_explain
node_dashboard -->|"reads trips"| node_dataset
node_dashboard -->|"reads metrics"| node_evaluation
node_dashboard -->|"loads model"| node_model
node_dashboard -->|"replays trips"| node_scoring
node_dashboard -->|"explains peak rows"| node_explain

click node_driveset "https://github.com/akashmeh/safecruise/tree/main/UAH-DRIVESET-v1"
click node_ingest "https://github.com/akashmeh/safecruise/blob/main/features.py"
click node_dataset "https://github.com/akashmeh/safecruise/blob/main/safe_cruise_full_dataset.csv.gz"
click node_engineering "https://github.com/akashmeh/safecruise/blob/main/features.py"
click node_training "https://github.com/akashmeh/safecruise/blob/main/train_full_model.py"
click node_model "https://github.com/akashmeh/safecruise/blob/main/safe_cruise_xgboost_model.pkl"
click node_evaluation "https://github.com/akashmeh/safecruise/blob/main/safe_cruise_eval.json"
click node_api "https://github.com/akashmeh/safecruise/blob/main/main.py"
click node_scoring "https://github.com/akashmeh/safecruise/blob/main/features.py"
click node_explain "https://github.com/akashmeh/safecruise/blob/main/features.py"
click node_dashboard "https://github.com/akashmeh/safecruise/blob/main/dashboard.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_ingest,node_dataset,node_engineering,node_scoring,node_explain,node_driver toneBlue
class node_training,node_model,node_evaluation toneAmber
class node_api toneMint
class node_dashboard toneRose
class node_driveset toneTeal
```

## Components

### Data and Features

- [Trip ingestion](https://github.com/akashmeh/safecruise/blob/main/features.py): `features.py`
- [Merged trip data](https://github.com/akashmeh/safecruise/blob/main/safe_cruise_full_dataset.csv.gz): `safe_cruise_full_dataset.csv.gz`
- [Temporal features](https://github.com/akashmeh/safecruise/blob/main/features.py): `features.py`
- [Risk scoring](https://github.com/akashmeh/safecruise/blob/main/features.py): `features.py`
- [SHAP explanations](https://github.com/akashmeh/safecruise/blob/main/features.py): `features.py`

### Model Lifecycle

- [Training and evaluation](https://github.com/akashmeh/safecruise/blob/main/train_full_model.py): `train_full_model.py`
- [XGBoost model](https://github.com/akashmeh/safecruise/blob/main/safe_cruise_xgboost_model.pkl): `safe_cruise_xgboost_model.pkl`
- [Evaluation artifacts](https://github.com/akashmeh/safecruise/blob/main/safe_cruise_eval.json): `safe_cruise_eval.json`

### Scoring Service

- [FastAPI endpoints](https://github.com/akashmeh/safecruise/blob/main/main.py): `main.py`

### Dashboard

- [Streamlit dashboard](https://github.com/akashmeh/safecruise/blob/main/dashboard.py): `dashboard.py`

### Other components

- **Telemetry client**
- [DriveSet trips](https://github.com/akashmeh/safecruise/tree/main/UAH-DRIVESET-v1): `UAH-DRIVESET-v1`

## Connections

- DriveSet trips → Trip ingestion: supplies trips
- Trip ingestion → Merged trip data: builds dataset
- Training and evaluation → Trip ingestion: loads data
- Training and evaluation → Temporal features: engineers features
- Training and evaluation → XGBoost model: writes model
- Training and evaluation → Evaluation artifacts: writes metrics
- Telemetry client → FastAPI endpoints: posts windows
- FastAPI endpoints → Risk scoring: scores windows
- Risk scoring → Temporal features: derives features
- Risk scoring → XGBoost model: loads model
- Risk scoring → SHAP explanations: requests attribution
- FastAPI endpoints → SHAP explanations: formats impacts
- Streamlit dashboard → Merged trip data: reads trips
- Streamlit dashboard → Evaluation artifacts: reads metrics
- Streamlit dashboard → XGBoost model: loads model
- Streamlit dashboard → Risk scoring: replays trips
- Streamlit dashboard → SHAP explanations: explains peak rows