Update README.md

README.md

@@ -1,322 +1,332 @@
-# 🌱 GreenPath: AI & Data Analytics Platform for Reducing Shipment CO₂ Emissions
-
-**Designed and Developed by Sayed Mohd Zayeem Khateeb**
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
-[![Streamlit](https://img.shields.io/badge/Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://streamlit.io/)
-[![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
-
-## 🎯 Overview
-
-GreenPath is an **AI-powered platform** that helps logistics and supply chain companies **measure, analyze, and reduce CO₂ emissions per shipment** while recommending **optimized delivery routes** that minimize emissions without significantly affecting delivery time or cost.
-
-### 🏆 Key Achievements
-- **22% reduction in CO₂ emissions** through green route optimization
-- **Real-time emission tracking** with IPCC-compliant calculations
-- **Multi-objective optimization** balancing emissions, cost, and delivery time
-- **Professional dashboard** with eco-friendly design and advanced analytics
-
-## 🌟 Core Features
-
-### 1. 🧮 CO₂ Emission Calculator
-- **Formula-based estimation**: `CO₂ = Distance × Weight × EmissionFactor`
-- **Multiple transport modes**: Road, Rail, Air, Ship (Container & Bulk)
-- **IPCC 2019 Guidelines compliance** for emission factors
-- **Carbon tax cost calculation** with customizable rates
-
-### 2. 🗺️ Green Route Recommendation Engine
-- **OpenRouteService API integration** for accurate routing
-- **Multi-modal transport optimization** (truck + rail combinations)
-- **Time constraint balancing** (max 10% time penalty for green options)
-- **Emission reduction visualization** with percentage improvements
-
-### 3. 📊 Analytics Dashboard
-- **Professional eco-friendly design** (green accents, clean layout)
-- **Real-time KPIs**: Total emissions, reduction percentage, carbon tax savings
-- **Interactive visualizations**: Transport mode comparison, emission trends
-- **Regional analysis** and performance metrics
-
-### 4. 📈 Business Impact Simulation
-- **Scenario analysis**: "What if X% shipments use optimized routes?"
-- **Financial impact**: Carbon tax savings and ESG score improvement
-- **ROI calculations** for sustainability investments
-- **Regulatory compliance** readiness assessment
-
-### 5. 📋 Comprehensive Reporting
-- **PDF reports** with executive summaries and recommendations
-- **Excel exports** with detailed shipment data and analytics
-- **Downloadable formats** for management review and compliance
-
-## 🚀 Quick Start
-
-### Option 1: Streamlit Web App (Recommended)
-```bash
-# Clone the repository
-git clone https://github.com/zayeemskhateeb-cloud/greenpath-ai-emission-tracker.git
-cd greenpath-ai-emission-tracker
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Run the Streamlit app
-streamlit run streamlit_app.py
-
-# Access at http://localhost:8501
-```
-
-### Option 2: FastAPI Backend + Frontend
-```bash
-# Terminal 1: Start FastAPI backend
-cd src/api
-python main.py
-# Backend available at http://localhost:8000
-
-# Terminal 2: Start Streamlit frontend
-streamlit run streamlit_app.py
-# Frontend available at http://localhost:8501
-```
-
-### Option 3: Docker Deployment
-```bash
-# Build and run with Docker Compose
-docker-compose up -d
-
-# Access services:
-# - Streamlit: http://localhost:8501
-# - FastAPI: http://localhost:8000
-# - API Docs: http://localhost:8000/docs
-```
-
-## 🛠️ Technology Stack
-
-### Backend & AI
-- **Python 3.8+** - Core programming language
-- **FastAPI** - High-performance API framework
-- **SQLAlchemy** - Database ORM with SQLite
-- **Pandas & NumPy** - Data processing and analytics
-- **Scikit-learn** - Machine learning capabilities
-
-### Frontend & Visualization
-- **Streamlit** - Interactive web application framework
-- **Plotly** - Advanced data visualizations
-- **Folium** - Interactive maps for route visualization
-- **Custom CSS** - Professional eco-friendly design
-
-### APIs & Integration
-- **OpenRouteService** - Route optimization and geocoding
-- **IPCC Emission Factors** - Scientifically accurate CO₂ calculations
-- **RESTful APIs** - Seamless integration capabilities
-
-### Reports & Export
-- **ReportLab** - Professional PDF report generation
-- **OpenPyXL** - Excel export functionality
-- **Custom templates** - Branded report formats
-
-## 📁 Project Structure
-
-```
-greenpath-ai-emission-tracker/
-├── src/
-│   ├── api/                    # FastAPI backend
-│   │   └── main.py            # API endpoints and logic
-│   ├── emissions/             # CO₂ calculation engine
-│   │   └── emission_calculator.py
-│   ├── route_optimizer/       # Green route optimization
-│   │   ���── green_route_optimizer.py
-│   ├── database/              # Data models and storage
-│   │   └── models.py
-│   └── reports/               # Report generation
-│       └── report_generator.py
-├── streamlit_app.py           # Main Streamlit application
-├── requirements.txt           # Python dependencies
-├── docker-compose.yml         # Container orchestration
-├── .env.example              # Environment variables template
-└── README.md                 # This file
-```
-
-## 🔧 Configuration
-
-### 1. Environment Setup
-```bash
-# Copy environment template
-cp .env.example .env
-
-# Add your API keys (optional for basic functionality)
-OPENROUTESERVICE_API_KEY=your_key_here
-DATABASE_URL=sqlite:///greenpath.db
-```
-
-### 2. API Keys (Optional)
-- **OpenRouteService**: For enhanced routing (free tier available)
-- **No API keys required** for basic emission calculations and demo functionality
-
-### 3. Database
-- **SQLite** (default): Automatic setup, no configuration needed
-- **PostgreSQL**: Update DATABASE_URL in .env for production
-
-## 📊 Usage Examples
-
-### Emission Calculator
-```python
-from src.emissions.emission_calculator import EmissionCalculator, TransportMode
-
-calculator = EmissionCalculator()
-
-# Calculate emissions for a truck shipment
-result = calculator.calculate_emissions(
-    distance_km=500,
-    weight_tonnes=2.5,
-    transport_mode=TransportMode.ROAD_TRUCK
-)
-
-print(f"CO₂ Emissions: {result['co2_emissions_kg']} kg")
-# Output: CO₂ Emissions: 77.5 kg
-```
-
-### Route Optimization
-```python
-from src.route_optimizer.green_route_optimizer import GreenRouteOptimizer
-
-optimizer = GreenRouteOptimizer()
-
-# Get green route recommendations
-recommendations = optimizer.recommend_green_routes(
-    origin="New York, NY",
-    destination="Los Angeles, CA",
-    weight_tonnes=5.0
-)
-
-print(f"Greenest option: {recommendations['summary']['greenest_option']}")
-```
-
-## 📈 Business Impact
-
-### Environmental Benefits
-- **Up to 22% reduction** in CO₂ emissions per shipment
-- **IPCC-compliant** emission calculations for accurate reporting
-- **Carbon footprint tracking** with detailed analytics
-- **ESG score improvement** through sustainability metrics
-
-### Financial Benefits
-- **Carbon tax savings**: Potential $1,250+ monthly savings
-- **Regulatory compliance**: Readiness for emission regulations
-- **Operational efficiency**: Optimized route planning
-- **Brand reputation**: Enhanced sustainability profile
-
-### Operational Benefits
-- **Real-time monitoring** of emission performance
-- **Data-driven decisions** with comprehensive analytics
-- **Scalable solution** for growing logistics operations
-- **Integration-ready** APIs for existing systems
-
-## 🎨 Design Philosophy
-
-### Eco-Friendly Theme
-- **Primary Color**: 🌱 Green (#2ECC71) for sustainability focus
-- **Secondary**: ⚪ Clean whites and soft greys (#F8F9FA)
-- **Accent**: 🔵 Professional navy (#34495E) for trust
-- **Typography**: Modern sans-serif fonts (Roboto, Inter)
-
-### User Experience
-- **Minimalist design** with purpose-driven interfaces
-- **Mobile responsive** layout for all devices
-- **Intuitive navigation** with clear visual hierarchy
-- **Professional aesthetics** suitable for enterprise use
-
-## 🚀 Deployment Options
-
-### 1. Streamlit Cloud (Recommended)
-```bash
-# Push to GitHub and deploy via Streamlit Cloud
-# Automatic deployment with GitHub integration
-```
-
-### 2. Heroku
-```bash
-# Deploy to Heroku with Procfile
-echo "web: streamlit run streamlit_app.py --server.port=\$PORT --server.address=0.0.0.0" > Procfile
-git add . && git commit -m "Deploy to Heroku"
-heroku create your-app-name
-git push heroku main
-```
-
-### 3. Docker Production
-```bash
-# Production deployment with Docker
-docker-compose -f docker-compose.prod.yml up -d
-```
-
-## 📋 API Documentation
-
-### FastAPI Endpoints
-- **GET** `/` - Health check and API information
-- **POST** `/calculate-emissions` - Calculate CO₂ emissions
-- **GET** `/compare-transport-modes` - Compare emission factors
-- **POST** `/optimize-route` - Get green route recommendations
-- **POST** `/scenario-analysis` - Business impact simulation
-- **GET** `/emission-factors` - IPCC emission factors reference
-
-### Interactive API Docs
-Access comprehensive API documentation at `http://localhost:8000/docs` when running the FastAPI backend.
-
-## 🧪 Testing & Validation
-
-### Emission Calculations
-- **IPCC 2019 Guidelines** compliance verification
-- **Transport mode accuracy** testing with real-world data
-- **Carbon tax calculations** with multiple rate scenarios
-
-### Route Optimization
-- **Multi-modal efficiency** testing across different distances
-- **Time penalty validation** within acceptable limits
-- **Cost-benefit analysis** for optimization recommendations
-
-## 🤝 Contributing
-
-We welcome contributions to improve GreenPath! Here's how to get started:
-
-1. **Fork the repository**
-2. **Create a feature branch**: `git checkout -b feature/AmazingFeature`
-3. **Commit your changes**: `git commit -m 'Add AmazingFeature'`
-4. **Push to the branch**: `git push origin feature/AmazingFeature`
-5. **Open a Pull Request**
-
-### Development Guidelines
-- Follow **PEP 8** Python style guidelines
-- Add **comprehensive docstrings** for new functions
-- Include **unit tests** for new features
-- Update **documentation** for API changes
-
-## 📄 License
-
-This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
-
-## 👨‍💻 Author
-
-**Sayed Mohd Zayeem Khateeb**
-- 🌐 **GitHub**: [@zayeemskhateeb-cloud](https://github.com/zayeemskhateeb-cloud)
-- 💼 **LinkedIn**: [Sayed Mohd Zayeem Khateeb](https://www.linkedin.com/in/zayeemkhateeb)
-- 📧 **Email**: [zayeem.s.khateeb@gmail.com](mailto:zayeem.s.khateeb@gmail.com)
-
-## 🙏 Acknowledgments
-
-- **IPCC** for emission factor guidelines and methodology
-- **OpenRouteService** for routing and geocoding services
-- **Streamlit** for the amazing web app framework
-- **FastAPI** for high-performance API development
-- **Open-source community** for excellent libraries and tools
-
-## 🌟 Star History
-
-If you find GreenPath helpful for your sustainability goals, please ⭐ **star this repository**!
-
----
-
-<div align="center">
-
-**🌱 GreenPath - Making Logistics Sustainable, One Route at a Time**
-
-*Designed with ❤️ for a greener future*
-
-</div>
+---
+title: GreenPath AI Emission Tracker
+emoji: 🌿
+colorFrom: green
+colorTo: blue
+sdk: streamlit
+sdk_version: "1.28.1"
+app_file: app.py
+pinned: true
+---
+# 🌱 GreenPath: AI & Data Analytics Platform for Reducing Shipment CO₂ Emissions
+
+**Designed and Developed by Sayed Mohd Zayeem Khateeb**
+
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Streamlit](https://img.shields.io/badge/Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://streamlit.io/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
+
+## 🎯 Overview
+
+GreenPath is an **AI-powered platform** that helps logistics and supply chain companies **measure, analyze, and reduce CO₂ emissions per shipment** while recommending **optimized delivery routes** that minimize emissions without significantly affecting delivery time or cost.
+
+### 🏆 Key Achievements
+- **22% reduction in CO₂ emissions** through green route optimization
+- **Real-time emission tracking** with IPCC-compliant calculations
+- **Multi-objective optimization** balancing emissions, cost, and delivery time
+- **Professional dashboard** with eco-friendly design and advanced analytics
+
+## 🌟 Core Features
+
+### 1. 🧮 CO₂ Emission Calculator
+- **Formula-based estimation**: `CO₂ = Distance × Weight × EmissionFactor`
+- **Multiple transport modes**: Road, Rail, Air, Ship (Container & Bulk)
+- **IPCC 2019 Guidelines compliance** for emission factors
+- **Carbon tax cost calculation** with customizable rates
+
+### 2. 🗺️ Green Route Recommendation Engine
+- **OpenRouteService API integration** for accurate routing
+- **Multi-modal transport optimization** (truck + rail combinations)
+- **Time constraint balancing** (max 10% time penalty for green options)
+- **Emission reduction visualization** with percentage improvements
+
+### 3. 📊 Analytics Dashboard
+- **Professional eco-friendly design** (green accents, clean layout)
+- **Real-time KPIs**: Total emissions, reduction percentage, carbon tax savings
+- **Interactive visualizations**: Transport mode comparison, emission trends
+- **Regional analysis** and performance metrics
+
+### 4. 📈 Business Impact Simulation
+- **Scenario analysis**: "What if X% shipments use optimized routes?"
+- **Financial impact**: Carbon tax savings and ESG score improvement
+- **ROI calculations** for sustainability investments
+- **Regulatory compliance** readiness assessment
+
+### 5. 📋 Comprehensive Reporting
+- **PDF reports** with executive summaries and recommendations
+- **Excel exports** with detailed shipment data and analytics
+- **Downloadable formats** for management review and compliance
+
+## 🚀 Quick Start
+
+### Option 1: Streamlit Web App (Recommended)
+```bash
+# Clone the repository
+git clone https://github.com/zayeemskhateeb-cloud/greenpath-ai-emission-tracker.git
+cd greenpath-ai-emission-tracker
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the Streamlit app
+streamlit run streamlit_app.py
+
+# Access at http://localhost:8501
+```
+
+### Option 2: FastAPI Backend + Frontend
+```bash
+# Terminal 1: Start FastAPI backend
+cd src/api
+python main.py
+# Backend available at http://localhost:8000
+
+# Terminal 2: Start Streamlit frontend
+streamlit run streamlit_app.py
+# Frontend available at http://localhost:8501
+```
+
+### Option 3: Docker Deployment
+```bash
+# Build and run with Docker Compose
+docker-compose up -d
+
+# Access services:
+# - Streamlit: http://localhost:8501
+# - FastAPI: http://localhost:8000
+# - API Docs: http://localhost:8000/docs
+```
+
+## 🛠️ Technology Stack
+
+### Backend & AI
+- **Python 3.8+** - Core programming language
+- **FastAPI** - High-performance API framework
+- **SQLAlchemy** - Database ORM with SQLite
+- **Pandas & NumPy** - Data processing and analytics
+- **Scikit-learn** - Machine learning capabilities
+
+### Frontend & Visualization
+- **Streamlit** - Interactive web application framework
+- **Plotly** - Advanced data visualizations
+- **Folium** - Interactive maps for route visualization
+- **Custom CSS** - Professional eco-friendly design
+
+### APIs & Integration
+- **OpenRouteService** - Route optimization and geocoding
+- **IPCC Emission Factors** - Scientifically accurate CO₂ calculations
+- **RESTful APIs** - Seamless integration capabilities
+
+### Reports & Export
+- **ReportLab** - Professional PDF report generation
+- **OpenPyXL** - Excel export functionality
+- **Custom templates** - Branded report formats
+
+## 📁 Project Structure
+
+```
+greenpath-ai-emission-tracker/
+├── src/
+│   ├── api/                    # FastAPI backend
+│   │   └── main.py            # API endpoints and logic
+│   ├── emissions/             # CO₂ calculation engine
+│   │   └── emission_calculator.py
+│   ├── route_optimizer/       # Green route optimization
+│   │   └── green_route_optimizer.py
+│   ├── database/              # Data models and storage
+│   │   └── models.py
+│   └── reports/               # Report generation
+│       └── report_generator.py
+├── streamlit_app.py           # Main Streamlit application
+├── requirements.txt           # Python dependencies
+├── docker-compose.yml         # Container orchestration
+├── .env.example              # Environment variables template
+└── README.md                 # This file
+```
+
+## 🔧 Configuration
+
+### 1. Environment Setup
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Add your API keys (optional for basic functionality)
+OPENROUTESERVICE_API_KEY=your_key_here
+DATABASE_URL=sqlite:///greenpath.db
+```
+
+### 2. API Keys (Optional)
+- **OpenRouteService**: For enhanced routing (free tier available)
+- **No API keys required** for basic emission calculations and demo functionality
+
+### 3. Database
+- **SQLite** (default): Automatic setup, no configuration needed
+- **PostgreSQL**: Update DATABASE_URL in .env for production
+
+## 📊 Usage Examples
+
+### Emission Calculator
+```python
+from src.emissions.emission_calculator import EmissionCalculator, TransportMode
+
+calculator = EmissionCalculator()
+
+# Calculate emissions for a truck shipment
+result = calculator.calculate_emissions(
+    distance_km=500,
+    weight_tonnes=2.5,
+    transport_mode=TransportMode.ROAD_TRUCK
+)
+
+print(f"CO₂ Emissions: {result['co2_emissions_kg']} kg")
+# Output: CO₂ Emissions: 77.5 kg
+```
+
+### Route Optimization
+```python
+from src.route_optimizer.green_route_optimizer import GreenRouteOptimizer
+
+optimizer = GreenRouteOptimizer()
+
+# Get green route recommendations
+recommendations = optimizer.recommend_green_routes(
+    origin="New York, NY",
+    destination="Los Angeles, CA",
+    weight_tonnes=5.0
+)
+
+print(f"Greenest option: {recommendations['summary']['greenest_option']}")
+```
+
+## 📈 Business Impact
+
+### Environmental Benefits
+- **Up to 22% reduction** in CO₂ emissions per shipment
+- **IPCC-compliant** emission calculations for accurate reporting
+- **Carbon footprint tracking** with detailed analytics
+- **ESG score improvement** through sustainability metrics
+
+### Financial Benefits
+- **Carbon tax savings**: Potential $1,250+ monthly savings
+- **Regulatory compliance**: Readiness for emission regulations
+- **Operational efficiency**: Optimized route planning
+- **Brand reputation**: Enhanced sustainability profile
+
+### Operational Benefits
+- **Real-time monitoring** of emission performance
+- **Data-driven decisions** with comprehensive analytics
+- **Scalable solution** for growing logistics operations
+- **Integration-ready** APIs for existing systems
+
+## 🎨 Design Philosophy
+
+### Eco-Friendly Theme
+- **Primary Color**: 🌱 Green (#2ECC71) for sustainability focus
+- **Secondary**: ⚪ Clean whites and soft greys (#F8F9FA)
+- **Accent**: 🔵 Professional navy (#34495E) for trust
+- **Typography**: Modern sans-serif fonts (Roboto, Inter)
+
+### User Experience
+- **Minimalist design** with purpose-driven interfaces
+- **Mobile responsive** layout for all devices
+- **Intuitive navigation** with clear visual hierarchy
+- **Professional aesthetics** suitable for enterprise use
+
+## 🚀 Deployment Options
+
+### 1. Streamlit Cloud (Recommended)
+```bash
+# Push to GitHub and deploy via Streamlit Cloud
+# Automatic deployment with GitHub integration
+```
+
+### 2. Heroku
+```bash
+# Deploy to Heroku with Procfile
+echo "web: streamlit run streamlit_app.py --server.port=\$PORT --server.address=0.0.0.0" > Procfile
+git add . && git commit -m "Deploy to Heroku"
+heroku create your-app-name
+git push heroku main
+```
+
+### 3. Docker Production
+```bash
+# Production deployment with Docker
+docker-compose -f docker-compose.prod.yml up -d
+```
+
+## 📋 API Documentation
+
+### FastAPI Endpoints
+- **GET** `/` - Health check and API information
+- **POST** `/calculate-emissions` - Calculate CO₂ emissions
+- **GET** `/compare-transport-modes` - Compare emission factors
+- **POST** `/optimize-route` - Get green route recommendations
+- **POST** `/scenario-analysis` - Business impact simulation
+- **GET** `/emission-factors` - IPCC emission factors reference
+
+### Interactive API Docs
+Access comprehensive API documentation at `http://localhost:8000/docs` when running the FastAPI backend.
+
+## 🧪 Testing & Validation
+
+### Emission Calculations
+- **IPCC 2019 Guidelines** compliance verification
+- **Transport mode accuracy** testing with real-world data
+- **Carbon tax calculations** with multiple rate scenarios
+
+### Route Optimization
+- **Multi-modal efficiency** testing across different distances
+- **Time penalty validation** within acceptable limits
+- **Cost-benefit analysis** for optimization recommendations
+
+## 🤝 Contributing
+
+We welcome contributions to improve GreenPath! Here's how to get started:
+
+1. **Fork the repository**
+2. **Create a feature branch**: `git checkout -b feature/AmazingFeature`
+3. **Commit your changes**: `git commit -m 'Add AmazingFeature'`
+4. **Push to the branch**: `git push origin feature/AmazingFeature`
+5. **Open a Pull Request**
+
+### Development Guidelines
+- Follow **PEP 8** Python style guidelines
+- Add **comprehensive docstrings** for new functions
+- Include **unit tests** for new features
+- Update **documentation** for API changes
+
+## 📄 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+
+## 👨‍💻 Author
+
+**Sayed Mohd Zayeem Khateeb**
+- 🌐 **GitHub**: [@zayeemskhateeb-cloud](https://github.com/zayeemskhateeb-cloud)
+- 💼 **LinkedIn**: [Sayed Mohd Zayeem Khateeb](https://www.linkedin.com/in/zayeemkhateeb)
+- 📧 **Email**: [zayeem.s.khateeb@gmail.com](mailto:zayeem.s.khateeb@gmail.com)
+
+## 🙏 Acknowledgments
+
+- **IPCC** for emission factor guidelines and methodology
+- **OpenRouteService** for routing and geocoding services
+- **Streamlit** for the amazing web app framework
+- **FastAPI** for high-performance API development
+- **Open-source community** for excellent libraries and tools
+
+## 🌟 Star History
+
+If you find GreenPath helpful for your sustainability goals, please ⭐ **star this repository**!
+
+---
+
+<div align="center">
+
+**🌱 GreenPath - Making Logistics Sustainable, One Route at a Time**
+
+*Designed with ❤️ for a greener future*
+
+</div>