diff --git a/README.md b/README.md
index 10dbdedd6091..3d338b453de3 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,112 @@
-# Welcome to Streamlit!
+ Diabetes Prediction System
 
-Edit `/streamlit_app.py` to customize this app to your heart's desire. :heart:
+A machine learning project that predicts whether a patient is likely to have diabetes based on medical measurements. The project uses the **Pima Indians Diabetes Dataset** and implements a complete machine learning workflow, including data preprocessing, model training, evaluation, model persistence, and prediction on new patient data.
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+
+
+ Project Overview
+
+This project demonstrates an end-to-end supervised machine learning pipeline using Python and scikit-learn. The model is trained to classify patients as either:
+
+0 – Not Diabetic
+1 – Diabetic
+
+The project includes:
+
+* Data loading and exploration
+* Data cleaning and preprocessing
+* Feature scaling
+* Train/test split
+* Model training
+* Model evaluation
+* Cross-validation
+* Saving the trained model
+* Predicting diabetes for new patient inputs
+
+
+
+## Dataset
+
+The project uses the **Pima Indians Diabetes Dataset**, which contains medical information for female patients of Pima Indian heritage.
+
+
+### Target
+
+Outcome 
+`0` = Not Diabetic
+`1` = Diabetic
+
+## Technologies Used
+* Python
+* Pandas
+* NumPy
+* Matplotlib
+* Seaborn
+* Scikit-learn
+* Joblib
+* Jupyter Notebook
+* Streamlit
+
+
+## Project Structure
+.
+├──
+├── FirstML.ipynb              # Data analysis, preprocessing, training and evaluation
+├── predict_diabetes.ipynb     # Predict diabetes using the trained model
+├── diabetes_model.pkl         # Saved machine learning model
+├── diabetes_scaler.pkl        # Saved StandardScaler
+└── README.md
+
+## Model Workflow
+1. Load the dataset.
+2. Explore and clean the data.
+3. Replace invalid zero values with missing values where appropriate.
+4. Fill missing values using the median.
+5. Split the dataset into training and testing sets.
+6. Scale the features using `StandardScaler`.
+7. Train the machine learning model.
+8. Evaluate performance using:
+   * Accuracy
+   * Confusion Matrix
+   * Classification Report
+   * ROC-AUC Score
+   * Cross-validation
+9. Save the trained model and scaler using Joblib.
+10. Predict diabetes risk for new patient data.
+
+## Example Results
+Example model performance:
+
+* Accuracy: **77.3%**
+* ROC-AUC: **0.834**
+* Mean Cross-Validation F1 Score: **0.672**
+
+## How to Run
+### 1. Clone the repository
+```bash
+git clone https://github.com/timdav-tech/predict_daibetes.git
+cd predict_daibetes
+```
+### 2. Install dependencies
+```bash
+pip install pandas numpy matplotlib seaborn scikit-learn joblib streamlit
+```
+### 3. Run the notebook
+Open: 
+predict_patient.ipynb
+to train and evaluate the model.
+
+### 4. Make predictions
+Run:
+predict_diabetes.ipynb
+and enter the requested patient information.
+
+## Future Improvements
+* Hyperparameter tuning
+* Compare multiple machine learning algorithms
+* Feature selection
+* Improve prediction accuracy through model optimization
+
+## Disclaimer
+This project is intended for educational and research purposes only. The predictions generated by the model are **not medical diagnoses** and should not replace professional medical advice.
+Always consult a qualified healthcare professional for diagnosis and treatment.