# sonnguyen129/accident-severity-prediction architecture

> Architecture diagram of the GitHub repository sonnguyen129/accident-severity-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sonnguyen129/accident-severity-prediction
- Repository: https://github.com/sonnguyen129/accident-severity-prediction

## Overview

##### Project Type and Purpose
- This is a machine learning web application that predicts road traffic accident severity using a trained XGBoost model. The application has an interactive front-end built with Streamlit and is deployed on Heroku. The project includes both training (data preprocessing, model training, evaluation) and production components (web UI for prediction).

##### File Structure
- Top-Level Files:
- app.py: The main Streamlit application.
- prediction.py: A separate script likely used for batch or API-based predictions.
- config.py: Contains configuration parameters.
- requirements.txt, runtime.txt, Procfile, setup.sh: Deployment and configuration files for Heroku.
- Directories:
- dataset: Contains the raw input dataset (RTA_Dataset.csv).
- doc: Contains documentation assets (for example, a demo GIF).
- model: Stores the trained ML artifacts (checkpoint.pkl and model_xgb.bin).
- notebooks: Contains Jupyter notebooks for exploratory data analysis and model building.

##### Extracting Architectural Insights from the README
- The README explains the ML pipeline (data exploration, preprocessing including imputation and balancing, feature selection, training via XGBoost with cross-validation and hyper-parameter tuning, and explainability using SHAP).
- It also highlights the separation of concerns – the offline workflow (model training and analysis within notebooks) and the production environment (Streamlit web application and prediction scripts).

##### Main Components
a. User Interface / Frontend:
- Streamlit application (app.py) as the entry point for end-users.
b. ML Prediction / Inference Engine:
- Prediction.py component that ties into the model-loading process.
- Model storage (model directory with checkpoint.pkl and model_xgb.bin) from which predictions are made.
c. Configuration and Environment:
- Config.py which supplies configuration details to both training and inference modules.
d. Offline Training / Data Processing Pipeline:
- Data ingestion from the dataset directory (RTA_Dataset.csv).
- Notebooks directory to indicate that exploratory data analysis and model building occurred offline.
- Mention that preprocessing, handling of missing values, SMOTE for balancing, and feature selection were key data pipeline steps.
e. Deployment / Cloud Component:
- That the entire web application is deployed on Heroku.
- Heroku as the cloud hosting component interacting with the front-end and backend services.

##### Relationships and Data Flows
- A directional flow from data ingestion (raw CSV file in the dataset) to the model training phase (notebooks and scripts) that produces saved model artifacts.
- User requests (via the Streamlit UI) being processed through the prediction module and then returning outputs (predictions and possibly SHAP-based explanations).

##### Architectural Patterns & Technologies
- Separation between offline (training/preprocessing) and online (production inference) environments.
- Use of a configuration management approach (via config.py) and the utilization of external services (Heroku deployment).
- Technologies (Python, XGBoost, SMOTE, SHAP, Streamlit) as labels near the corresponding components.

##### Putting It All Together
- Drill down further into how the front-end (Streamlit) connects to the backend (prediction.py and model serving), which in turn retrieves the model from stored files.
- Finally, reference the offline training components as a separate segment that produced the artifacts now in use.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global components
    U["User"]:::user
    H["Heroku Cloud"]:::heroku

    %% Configuration & Deployment subgraph
    subgraph "Configuration & Deployment"
        C["Configuration (config.py)"]:::config
        P["Procfile"]:::config
        R["runtime.txt"]:::config
        Q["requirements.txt"]:::config
        S["setup.sh"]:::config
    end

    %% Production pipeline
    F["Streamlit Frontend (app.py)"]:::online
    PS["Prediction Service (prediction.py)"]:::online

    subgraph "Model Artifacts"
        A1["Model Artifact: checkpoint.pkl"]:::online
        A2["Model Artifact: model_xgb.bin"]:::online
    end

    %% Offline Training Pipeline subgraph
    subgraph "Offline Training Pipeline"
        D["Raw Data (RTA_Dataset.csv)"]:::offline
        N["Exploratory Analysis & Training (Notebooks)"]:::offline
    end

    %% Connections
    U -->|"accesses"| H
    H -->|"deploys"| F
    H -->|"deploys"| PS
    H -->|"hosts"| C

    C -->|"configures"| F
    C -->|"configures"| PS

    F -->|"calls"| PS
    PS -->|"loads"| A1
    PS -->|"loads"| A2

    D -->|"feeds"| N
    N -->|"produces"| A1
    N -->|"produces"| A2

    %% Styles
    classDef user fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
    classDef heroku fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
    classDef online fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef config fill:#FFECB3,stroke:#FFA000,stroke-width:2px;
    classDef offline fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;

    %% Click events
    click F "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/app.py"
    click PS "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/prediction.py"
    click A1 "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/model/checkpoint.pkl"
    click A2 "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/model/model_xgb.bin"
    click C "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/config.py"
    click P "https://github.com/sonnguyen129/accident-severity-prediction/tree/main/Procfile"
    click R "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/runtime.txt"
    click Q "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/requirements.txt"
    click S "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/setup.sh"
    click D "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/dataset/RTA_Dataset.csv"
    click N "https://github.com/sonnguyen129/accident-severity-prediction/blob/main/notebooks/modeling.ipynb"
```
