# abdulrahimabubakari/ev-battery-soh-api architecture

> Architecture diagram of the GitHub repository abdulrahimabubakari/ev-battery-soh-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdulrahimabubakari/ev-battery-soh-api
- Repository: https://github.com/abdulrahimabubakari/ev-battery-soh-api

## Overview

This repository is an EV battery State-of-Health prediction product: users submit cycle features or raw CSV data through a React dashboard/API and receive SoH estimates and degradation visualizations. A separate ML workflow prepares labeled cycle data, engineers physics-based features, adds cycle context, and trains and tracks models. The graph also preserves the documented model-info and health capabilities. Source excerpts show the API and key training steps; unsampled runtime details and the absent model artifact limit further wiring claims.

Main entry points: [`data`](https://github.com/abdulrahimabubakari/ev-battery-soh-api/tree/master/data) (Feature table), [`api/main.py`](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/api/main.py) (FastAPI endpoints), [`frontend/src/App.js`](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/App.js) (SoH dashboard), [`frontend/src/index.js`](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/index.js) (React entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard["SoH dashboard<br/>[App.js]"]
  node_frontend_entry["React entry<br/>[index.js]"]
  node_vitals["Web vitals<br/>[reportWebVitals.js]"]
end

subgraph group_serving["Prediction API"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_model_artifact["LightGBM artifact"]
end

subgraph group_preparation["Data Preparation"]
  node_cycles[("Cycle CSV data")]
  node_exploration["Label cycles"]
  node_features["Feature extraction"]
  node_cycle_enrichment["Cycle enrichment"]
  node_feature_table[("Feature table")]
end

subgraph group_training["Model Training"]
  node_lightgbm_training["LightGBM training<br/>[train_lightgbm.py]"]
  node_xgboost_training["XGBoost training<br/>[train_model.py]"]
end

node_operator(("Battery analyst"))
node_mlflow[("MLflow tracking")]

node_operator -->|"uses"| node_dashboard
node_frontend_entry -->|"renders"| node_dashboard
node_frontend_entry -->|"invokes"| node_vitals
node_dashboard -->|"requests predictions"| node_api
node_api -->|"loads model"| node_model_artifact
node_api -->|"predicts with"| node_model_artifact
node_exploration -->|"writes labels"| node_cycles
node_features -->|"reads cycles"| node_cycles
node_features -->|"writes features"| node_feature_table
node_cycle_enrichment -->|"updates features"| node_feature_table
node_lightgbm_training -->|"reads features"| node_feature_table
node_xgboost_training -->|"reads features"| node_feature_table
node_lightgbm_training -->|"logs run"| node_mlflow
node_xgboost_training -->|"logs run"| node_mlflow

click node_dashboard "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/App.js"
click node_frontend_entry "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/index.js"
click node_vitals "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/reportWebVitals.js"
click node_api "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/api/main.py"
click node_model_artifact "https://github.com/abdulrahimabubakari/ev-battery-soh-api/tree/master/src"
click node_cycles "https://github.com/abdulrahimabubakari/ev-battery-soh-api/tree/master/data"
click node_exploration "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/notebooks/01_data_exploration.py"
click node_features "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/feature_engineering.py"
click node_cycle_enrichment "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/add_cycle_number.py"
click node_feature_table "https://github.com/abdulrahimabubakari/ev-battery-soh-api/tree/master/data"
click node_lightgbm_training "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/train_lightgbm.py"
click node_xgboost_training "https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/train_model.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_dashboard,node_frontend_entry,node_vitals toneBlue
class node_api,node_model_artifact,node_mlflow toneAmber
class node_cycles,node_exploration,node_features,node_cycle_enrichment,node_feature_table toneMint
class node_lightgbm_training,node_xgboost_training toneRose
class node_operator toneIndigo
```

## Components

### Dashboard

- [SoH dashboard](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/App.js): `frontend/src/App.js`
- [React entry](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/index.js): `frontend/src/index.js`
- [Web vitals](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/frontend/src/reportWebVitals.js): `frontend/src/reportWebVitals.js`

### Prediction API

- [FastAPI endpoints](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/api/main.py): `api/main.py`
- [LightGBM artifact](https://github.com/abdulrahimabubakari/ev-battery-soh-api/tree/master/src): `src`

### Data Preparation

- [Cycle CSV data](https://github.com/abdulrahimabubakari/ev-battery-soh-api/tree/master/data): `data`
- [Label cycles](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/notebooks/01_data_exploration.py): `notebooks/01_data_exploration.py`
- [Feature extraction](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/feature_engineering.py): `src/feature_engineering.py`
- [Cycle enrichment](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/add_cycle_number.py): `src/add_cycle_number.py`
- [Feature table](https://github.com/abdulrahimabubakari/ev-battery-soh-api/tree/master/data): `data`

### Model Training

- [LightGBM training](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/train_lightgbm.py): `src/train_lightgbm.py`
- [XGBoost training](https://github.com/abdulrahimabubakari/ev-battery-soh-api/blob/master/src/train_model.py): `src/train_model.py`

### Other components

- **Battery analyst**
- **MLflow tracking**

## Connections

- Battery analyst → SoH dashboard: uses (evidence: `README.md`)
- React entry → SoH dashboard: renders (evidence: `frontend/src/index.js`)
- React entry → Web vitals: invokes (evidence: `frontend/src/index.js`)
- SoH dashboard → FastAPI endpoints: requests predictions (evidence: `frontend/src/App.js`)
- FastAPI endpoints → LightGBM artifact: loads model (evidence: `api/main.py`)
- FastAPI endpoints → LightGBM artifact: predicts with (evidence: `api/main.py`)
- Label cycles → Cycle CSV data: writes labels (evidence: `notebooks/01_data_exploration.py`)
- Feature extraction → Cycle CSV data: reads cycles (evidence: `src/feature_engineering.py`)
- Feature extraction → Feature table: writes features (evidence: `src/feature_engineering.py`)
- Cycle enrichment → Feature table: updates features (evidence: `src/add_cycle_number.py`)
- LightGBM training → Feature table: reads features (evidence: `src/train_lightgbm.py`)
- XGBoost training → Feature table: reads features (evidence: `src/train_model.py`)
- LightGBM training → MLflow tracking: logs run (evidence: `src/train_lightgbm.py`)
- XGBoost training → MLflow tracking: logs run (evidence: `src/train_model.py`)
