docs/architecture.md

# Architecture Overview

## System Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                    Docker Container (port 7860)                   │
├──────────────┬───────────────┬───────────────────────────────────┤
│  React SPA   │  Gradio UI    │  FastAPI Backend                  │
│  (static)    │  /gradio      │  /api/*     /docs     /health     │
│  /           │               │                                    │
├──────────────┴───────────────┴───────────────────────────────────┤
│                      Model Registry                               │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │Classical │  │ LSTM×4   │  │Transform.│  │ Ensemble │          │
│  │ models   │  │ GRU      │  │ GPT, TFT │  │ Stack/WA │          │
│  └─────────┘  └──────────┘  └──────────┘  └──────────┘          │
├──────────────────────────────────────────────────────────────────┤
│                  Data Pipeline (src/)                              │
│  loader.py → features.py → preprocessing.py → model training     │
├──────────────────────────────────────────────────────────────────┤
│                 NASA PCoE Dataset (cleaned_dataset/)              │
└──────────────────────────────────────────────────────────────────┘
```

## Data Flow

1. **Ingestion:** `loader.py` reads metadata.csv + per-cycle CSVs
2. **Feature Engineering:** `features.py` computes SOC, SOH, RUL, scalar features per cycle
3. **Preprocessing:** `preprocessing.py` creates sliding windows, scales features, splits by battery
4. **Training:** Notebooks train each model family, save checkpoints to `artifacts/models/`
5. **Serving:** `model_registry.py` loads all models at startup
6. **Prediction:** API receives features → registry dispatches to best model → returns SOH/RUL
7. **Simulation:** `POST /api/v2/simulate` receives multi-battery config → vectorized Arrhenius degradation + ML via `predict_array()` → returns per-step SOH, RUL, and degradation-state history for each battery
8. **Visualization:** Frontend fetches results and renders analytics (fleet overview, compare, temperature analysis, recommendations)

## Model Registry

The `ModelRegistry` singleton:
- Scans `artifacts/models/classical/` for `.joblib` files (sklearn/xgb/lgbm)
- Scans `artifacts/models/deep/` for `.pt` (PyTorch) and `.keras` (TF) files
- Loads classical models eagerly; deep models registered lazily
- Selects default model by priority: XGBoost > LightGBM > RandomForest > Ridge > deep models
- Provides unified `predict()` interface regardless of framework
- `predict_array(X: np.ndarray, model_name: str)` batch method enables vectorized simulation: accepts an (N, n_features) array and returns predictions for all N cycles in one call, avoiding Python loops
- `_x_for_model()` normalizes input feature extraction for both single-cycle and batch paths
- `_load_scaler()` lazily loads per-model scalers from `artifacts/scalers/`

## Frontend Architecture

- **Vite 7** build tool with React 19 + TypeScript 5.9
- **lucide-react 0.575** for all icons — no emojis used anywhere in the UI
- **Recharts 3** for all 2D charts (BarChart, AreaChart, LineChart, ScatterChart, RadarChart, PieChart)
- **TailwindCSS 4** for styling
- Tabs: Simulation | Predict | Metrics | Analytics | Recommendations | Research Paper
- API proxy in dev mode (`/api` → `localhost:7860`) → same-origin in production (served by FastAPI)
- **Analytics (GraphPanel):** 4-section dashboard — Fleet Overview (health kpi, fleet SOH bar, bubble scatter), Single Battery (SOH + RUL projection, capacity fade, degradation rate), Compare (multi-battery overlay), Temperature Analysis
- **Metrics (MetricsPanel):** 6-section interactive dashboard — Overview KPIs, Models (sort/filter/chart-type controls), Validation, Deep Learning, Dataset stats, Figures searchable gallery
- **Recommendations (RecommendationPanel):** Slider inputs for SOH/temp, 3 chart tabs (RUL bar, params bar, top-3 radar), expandable table rows with per-recommendation explanation