# saidattaputta/homevalue-ai architecture

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

- Interactive diagram: https://gitdiagram.com/saidattaputta/homevalue-ai
- Repository: https://github.com/saidattaputta/homevalue-ai

## Overview

HomeValue-AI is a residential-price prediction product with Streamlit interfaces and a FastAPI inference backend. Users enter one property's features or upload a batch for prediction; API routes pass the resulting data to the prediction pipeline, which prepares features, applies the saved preprocessor and Ridge model, and returns prices. The repository also documents a training and explainability workflow, and the dashboard presents model metrics and SHAP outputs. UI/API wiring is supported by the README; some training-stage connections are documented rather than verified in sampled source.

Main entry points: [`src/pipelines/pipeline.py`](https://github.com/saidattaputta/homevalue-ai/blob/main/src/pipelines/pipeline.py) (Prediction Pipeline), [`src/visualization/shap_explainability.py`](https://github.com/saidattaputta/homevalue-ai/blob/main/src/visualization/shap_explainability.py) (SHAP Analysis), [`app/pages/4_Model_Insights.py`](https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/4_Model_Insights.py) (Insights Dashboard), [`app/pages/2_Predict.py`](https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/2_Predict.py) (Single Prediction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit Dashboard"]
  node_single["Single Prediction<br/>[2_Predict.py]"]
  node_batch["Batch Prediction<br/>[3_Batch_Predict.py]"]
  node_form["Property Form<br/>[forms.py]"]
  node_dashboard["Home Dashboard<br/>[1_Home.py]"]
end

subgraph group_api["Inference API"]
  node_api_service["FastAPI Service<br/>[main.py]"]
  node_routes["Prediction Routes<br/>[routes.py]"]
  node_schemas["Request Schemas<br/>[schemas.py]"]
end

subgraph group_ml["Prediction Pipeline"]
  node_pipeline["Prediction Pipeline<br/>[pipeline.py]"]
  node_cleaning["Inference Cleaning<br/>[data_cleaning.py]"]
  node_features["Feature Engineering"]
  node_preprocessor["Saved Preprocessor<br/>[preprocessor.pkl]"]
  node_model["Ridge Model<br/>[best_model.pkl]"]
  node_frequency["Category Frequencies"]
end

subgraph group_training["Model Development"]
  node_raw_data["Raw Housing Data"]
  node_cleaning_train["Data Cleaning<br/>[data_cleaning.py]"]
  node_engineering_train["Feature Engineering"]
  node_preprocessing_train["Preprocessing<br/>[preprocessing.py]"]
  node_training_model["Model Training<br/>[model_training.py]"]
  node_tuning["Hyperparameter Tuning"]
end

subgraph group_insights["Model Insights"]
  node_shap["SHAP Analysis"]
  node_insight_page["Insights Dashboard"]
  node_comparison["Model Comparison<br/>[comparision.csv]"]
  node_shap_artifacts["SHAP Outputs"]
end

node_user(("User"))
node_api_client(("REST API"))

node_user -->|"opens"| node_dashboard
node_user -->|"requests"| node_single
node_user -->|"uploads CSV"| node_batch
node_single -->|"collects features"| node_form
node_single -->|"submits prediction"| node_api_client
node_batch -->|"submits batch"| node_api_client
node_api_client -->|"REST request"| node_api_service
node_api_service -->|"registers routes"| node_routes
node_routes -->|"validates requests"| node_schemas
node_routes -->|"calls predict"| node_pipeline
node_pipeline -->|"cleans features"| node_cleaning
node_pipeline -->|"engineers features"| node_features
node_pipeline -->|"loads and transforms"| node_preprocessor
node_pipeline -->|"loads and predicts"| node_model
node_pipeline -->|"reads frequencies"| node_frequency
node_raw_data -->|"feeds documented workflow"| node_cleaning_train
node_cleaning_train -->|"clean then engineer"| node_engineering_train
node_engineering_train -->|"engineer then preprocess"| node_preprocessing_train
node_preprocessing_train -->|"prepares training data"| node_training_model
node_training_model -->|"tunes model"| node_tuning
node_insight_page -->|"reads metrics"| node_comparison
node_insight_page -->|"displays explanations"| node_shap_artifacts
node_insight_page -.->|"SHAP capability"| node_shap
node_shap -->|"loads preprocessor"| node_preprocessor
node_shap -->|"loads model"| node_model
node_shap -->|"writes plots and values"| node_shap_artifacts

click node_single "https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/2_Predict.py"
click node_batch "https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/3_Batch_Predict.py"
click node_form "https://github.com/saidattaputta/homevalue-ai/blob/main/app/components/forms.py"
click node_dashboard "https://github.com/saidattaputta/homevalue-ai/blob/main/app/1_Home.py"
click node_api_service "https://github.com/saidattaputta/homevalue-ai/blob/main/api/main.py"
click node_routes "https://github.com/saidattaputta/homevalue-ai/blob/main/api/routes.py"
click node_schemas "https://github.com/saidattaputta/homevalue-ai/blob/main/api/schemas.py"
click node_pipeline "https://github.com/saidattaputta/homevalue-ai/blob/main/src/pipelines/pipeline.py"
click node_cleaning "https://github.com/saidattaputta/homevalue-ai/blob/main/src/data/data_cleaning.py"
click node_features "https://github.com/saidattaputta/homevalue-ai/blob/main/src/features/feature_engineering.py"
click node_preprocessor "https://github.com/saidattaputta/homevalue-ai/blob/main/artifacts/preprocessor.pkl"
click node_model "https://github.com/saidattaputta/homevalue-ai/blob/main/models/best_model.pkl"
click node_frequency "https://github.com/saidattaputta/homevalue-ai/blob/main/artifacts/categorical_frequencies.json"
click node_raw_data "https://github.com/saidattaputta/homevalue-ai/tree/main/data/raw"
click node_cleaning_train "https://github.com/saidattaputta/homevalue-ai/blob/main/src/data/data_cleaning.py"
click node_engineering_train "https://github.com/saidattaputta/homevalue-ai/blob/main/src/features/feature_engineering.py"
click node_preprocessing_train "https://github.com/saidattaputta/homevalue-ai/blob/main/src/preprocessing/preprocessing.py"
click node_training_model "https://github.com/saidattaputta/homevalue-ai/blob/main/src/models/model_training.py"
click node_tuning "https://github.com/saidattaputta/homevalue-ai/blob/main/src/models/hyperparameter_tuning.py"
click node_shap "https://github.com/saidattaputta/homevalue-ai/blob/main/src/visualization/shap_explainability.py"
click node_insight_page "https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/4_Model_Insights.py"
click node_comparison "https://github.com/saidattaputta/homevalue-ai/blob/main/artifacts/comparision.csv"
click node_shap_artifacts "https://github.com/saidattaputta/homevalue-ai/tree/main/artifacts"

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_single,node_batch,node_form,node_dashboard,node_user toneBlue
class node_api_service,node_routes,node_schemas toneAmber
class node_pipeline,node_cleaning,node_features,node_preprocessor,node_model,node_frequency,node_api_client toneMint
class node_raw_data,node_cleaning_train,node_engineering_train,node_preprocessing_train,node_training_model,node_tuning toneRose
class node_shap,node_insight_page,node_comparison,node_shap_artifacts toneIndigo
```

## Components

### Streamlit Dashboard

- [Single Prediction](https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/2_Predict.py): `app/pages/2_Predict.py`
- [Batch Prediction](https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/3_Batch_Predict.py): `app/pages/3_Batch_Predict.py`
- [Property Form](https://github.com/saidattaputta/homevalue-ai/blob/main/app/components/forms.py): `app/components/forms.py`
- [Home Dashboard](https://github.com/saidattaputta/homevalue-ai/blob/main/app/1_Home.py): `app/1_Home.py`

### Inference API

- [FastAPI Service](https://github.com/saidattaputta/homevalue-ai/blob/main/api/main.py): `api/main.py`
- [Prediction Routes](https://github.com/saidattaputta/homevalue-ai/blob/main/api/routes.py): `api/routes.py`
- [Request Schemas](https://github.com/saidattaputta/homevalue-ai/blob/main/api/schemas.py): `api/schemas.py`

### Prediction Pipeline

- [Prediction Pipeline](https://github.com/saidattaputta/homevalue-ai/blob/main/src/pipelines/pipeline.py): `src/pipelines/pipeline.py`
- [Inference Cleaning](https://github.com/saidattaputta/homevalue-ai/blob/main/src/data/data_cleaning.py): `src/data/data_cleaning.py`
- [Feature Engineering](https://github.com/saidattaputta/homevalue-ai/blob/main/src/features/feature_engineering.py): `src/features/feature_engineering.py`
- [Saved Preprocessor](https://github.com/saidattaputta/homevalue-ai/blob/main/artifacts/preprocessor.pkl): `artifacts/preprocessor.pkl`
- [Ridge Model](https://github.com/saidattaputta/homevalue-ai/blob/main/models/best_model.pkl): `models/best_model.pkl`
- [Category Frequencies](https://github.com/saidattaputta/homevalue-ai/blob/main/artifacts/categorical_frequencies.json): `artifacts/categorical_frequencies.json`

### Model Development

- [Raw Housing Data](https://github.com/saidattaputta/homevalue-ai/tree/main/data/raw): `data/raw`
- [Data Cleaning](https://github.com/saidattaputta/homevalue-ai/blob/main/src/data/data_cleaning.py): `src/data/data_cleaning.py`
- [Feature Engineering](https://github.com/saidattaputta/homevalue-ai/blob/main/src/features/feature_engineering.py): `src/features/feature_engineering.py`
- [Preprocessing](https://github.com/saidattaputta/homevalue-ai/blob/main/src/preprocessing/preprocessing.py): `src/preprocessing/preprocessing.py`
- [Model Training](https://github.com/saidattaputta/homevalue-ai/blob/main/src/models/model_training.py): `src/models/model_training.py`
- [Hyperparameter Tuning](https://github.com/saidattaputta/homevalue-ai/blob/main/src/models/hyperparameter_tuning.py): `src/models/hyperparameter_tuning.py`

### Model Insights

- [SHAP Analysis](https://github.com/saidattaputta/homevalue-ai/blob/main/src/visualization/shap_explainability.py): `src/visualization/shap_explainability.py`
- [Insights Dashboard](https://github.com/saidattaputta/homevalue-ai/blob/main/app/pages/4_Model_Insights.py): `app/pages/4_Model_Insights.py`
- [Model Comparison](https://github.com/saidattaputta/homevalue-ai/blob/main/artifacts/comparision.csv): `artifacts/comparision.csv`
- [SHAP Outputs](https://github.com/saidattaputta/homevalue-ai/tree/main/artifacts): `artifacts`

### Other components

- **User**
- **REST API**

## Connections

- User → Home Dashboard: opens
- User → Single Prediction: requests
- User → Batch Prediction: uploads CSV
- Single Prediction → Property Form: collects features
- Single Prediction → REST API: submits prediction
- Batch Prediction → REST API: submits batch
- REST API → FastAPI Service: REST request
- FastAPI Service → Prediction Routes: registers routes
- Prediction Routes → Request Schemas: validates requests
- Prediction Routes → Prediction Pipeline: calls predict
- Prediction Pipeline → Inference Cleaning: cleans features
- Prediction Pipeline → Feature Engineering: engineers features
- Prediction Pipeline → Saved Preprocessor: loads and transforms
- Prediction Pipeline → Ridge Model: loads and predicts
- Prediction Pipeline → Category Frequencies: reads frequencies
- Raw Housing Data → Data Cleaning: feeds documented workflow
- Data Cleaning → Feature Engineering: clean then engineer
- Feature Engineering → Preprocessing: engineer then preprocess
- Preprocessing → Model Training: prepares training data
- Model Training → Hyperparameter Tuning: tunes model
- Insights Dashboard → Model Comparison: reads metrics
- Insights Dashboard → SHAP Outputs: displays explanations
- Insights Dashboard → SHAP Analysis: SHAP capability
- SHAP Analysis → Saved Preprocessor: loads preprocessor
- SHAP Analysis → Ridge Model: loads model
- SHAP Analysis → SHAP Outputs: writes plots and values