# parthita/powergrid_ml_sih architecture

> Architecture diagram of the GitHub repository parthita/powergrid_ml_sih, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parthita/powergrid_ml_sih
- Repository: https://github.com/parthita/powergrid_ml_sih

## Overview

##### Project Type and Purpose
- This is a full-stack web application.
- Purpose: Provide predictive insights (cost & timeline overruns) for power grid construction projects via an interactive dashboard.

##### File Structure
- Top-level folders:
- backend/ (FastAPI service, ML pipeline, model artifacts)
- frontend/ (React SPA)
- test_csvs/ (sample input CSVs)
- backend contains:
- api.py (FastAPI routes)
- schema.py (Pydantic request/response models)
- feature_engineering.py (data transformation pipeline)
- train_overrun.py & predict.py (model training & inference logic)
- best_models.pkl (serialized XGBoost models)
- requirements.txt & Procfile (deployment config)
- frontend contains:
- src/index.html, main.jsx, App.jsx (entrypoint & React components)
- vite.config.js, package.json (build tooling)
- No dedicated database—state is stateless, input is provided at request time, model lives in file system.

##### README for Additional Insights
- Architecture: two-tier decoupled design (Frontend SPA + Backend API).
- ML stack: Pandas, Scikit-learn, XGBoost, Joblib.
- Deployment: Railway (backend) & Vercel (frontend).
- Data flow: user uploads CSV → backend feature-engineering → XGBoost inference → JSON response → frontend visualization.

##### Main Components
a. Frontend SPA
- React App (App.jsx)
- Visualization library (Recharts)
- Deployed on Vercel
b. Backend API
- FastAPI service (api.py)
- Pydantic schemas (schema.py)
- Feature engineering module (feature_engineering.py)
- Model inference module (predict.py)
- Trained model artifacts (best_models.pkl)
- Deployed on Railway
c. External Services
- Vercel hosting (frontend)
- Railway hosting (backend)
d. Data Input
- CSV file (user-provided or test_csvs)
- HTTP POST request payload
e. Output
- JSON payload with `CostOverrunPct` & `TimelineOverrunPct`
- Dashboard charts/graphs

##### Relationships & Data Flow
1. User browser loads React SPA from Vercel
2. User selects or uploads a CSV of project data
3. SPA sends HTTP POST `/predict` (or similar) to FastAPI endpoint on Railway
4. FastAPI endpoint:
- Validates payload via Pydantic models
- Invokes feature_engineering pipeline
- Loads XGBoost models (best_models.pkl)
- Runs predictions
- Returns JSON with predictions
5. SPA receives JSON and renders interactive charts

##### Architectural Patterns & Principles
- Separation of concerns: UI logic vs. ML & API logic
- Stateless services: no database or session state
- Modular ML pipeline: clear separation between feature engineering, training, and inference
- Single responsibility: each module (schema, feature_engineering, predict) has a clear role

##### Diagramming Conventions
- Blue for frontend components
- Green for backend/API components
- Yellow for ML pipeline parts
- Gray for external services
- Endpoints (e.g., POST /predict) and data formats (CSV, JSON)

##### Essential Elements to Capture
- Client browser (User)
- React SPA (Static host on Vercel)
- FastAPI service (Deployed on Railway)
- Feature engineering & ML model modules
- Model artifact file (best_models.pkl)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Users and Input
    User["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ReactApp["React SPA"]:::frontend
        BuildTooling["Build & Tooling"]:::frontend
    end

    Vercel["Vercel Hosting"]:::external

    %% Data Input
    CSV["CSV File"]:::external

    %% Backend Layer
    subgraph "Backend API"
        direction TB
        API["FastAPI Service<br/>(POST /predict)"]:::backend
        Schemas["Pydantic Schemas"]:::backend
        subgraph "ML Pipeline"
            direction TB
            FE["Feature Engineering"]:::ml
            Infer["Model Inference"]:::ml
            ModelFile["XGBoost Model Artifact"]:::ml
        end
        Training["Model Training Logic"]:::ml
        DeployCfg["Backend Deployment Config"]:::backend
    end

    Railway["Railway Hosting"]:::external

    %% Data Flow
    User -->|"loads SPA"| Vercel
    Vercel -->|"serves React App"| ReactApp
    User -->|"uploads/selects"| CSV
    ReactApp -->|"POST /predict (CSV JSON)"| API
    API -->|"validate payload"| Schemas
    Schemas -->|"pass features"| FE
    FE -->|"transformed data"| Infer
    Infer -->|"loads model"| ModelFile
    Infer -->|"predicts overrun"| API
    API -->|"returns JSON"| ReactApp
    ReactApp -->|"renders charts"| User

    %% Deployment Links
    API --> Railway
    ReactApp --> Vercel

    %% Click Events
    click ReactApp "https://github.com/parthita/powergrid_ml_sih/blob/main/frontend/src/App.jsx"
    click ReactApp "https://github.com/parthita/powergrid_ml_sih/blob/main/frontend/src/main.jsx"
    click ReactApp "https://github.com/parthita/powergrid_ml_sih/blob/main/frontend/index.html"
    click BuildTooling "https://github.com/parthita/powergrid_ml_sih/blob/main/frontend/package.json"
    click BuildTooling "https://github.com/parthita/powergrid_ml_sih/blob/main/frontend/vite.config.js"
    click API "https://github.com/parthita/powergrid_ml_sih/blob/main/backend/api.py"
    click Schemas "https://github.com/parthita/powergrid_ml_sih/blob/main/backend/schema.py"
    click FE "https://github.com/parthita/powergrid_ml_sih/blob/main/backend/feature_engineering.py"
    click Infer "https://github.com/parthita/powergrid_ml_sih/blob/main/backend/predict.py"
    click Training "https://github.com/parthita/powergrid_ml_sih/blob/main/backend/train_overrun.py"
    click ModelFile "https://github.com/parthita/powergrid_ml_sih/blob/main/backend/best_models.pkl"
    click DeployCfg "https://github.com/parthita/powergrid_ml_sih/tree/main/backend/Procfile"
    click DeployCfg "https://github.com/parthita/powergrid_ml_sih/blob/main/backend/requirements.txt"
    click CSV "https://github.com/parthita/powergrid_ml_sih/blob/main/test_csvs/*.csv"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E6FFEA,stroke:#28a745,color:#28a745
    classDef ml fill:#FFF5BA,stroke:#E1A100,color:#E1A100
    classDef external fill:#F0F0F0,stroke:#888888,color:#555555
```
