OrganMatch - Organ Donation Matching Platform

# OrganMatch - Organ Donation Matching Platform

## Overview
OrganMatch is a production-ready, web-based organ donation matching system that uses Machine Learning (Random Forest) to predict donor-recipient compatibility. It aims to streamline the organ matching process for hospitals by identifying optimal matches based on medical, genetic, and geographical factors, thereby improving efficiency and saving lives. The platform includes robust authentication, real-time location features, automatic ML model retraining, comprehensive deployment configurations, and VS Code development optimizations.

## User Preferences
I want iterative development.
Ask before making major changes.
I prefer detailed explanations.
Do not make changes to the folder Z.
Do not make changes to the file Y.

## System Architecture
OrganMatch is built with Flask, SQLAlchemy, and scikit-learn, adhering to production-ready best practices including environment-based configuration and containerization support.

### UI/UX Decisions
The application features a comprehensive design system with a purple gradient theme (#667eea → #764ba2), glassmorphism effects, and a professional component library. It uses Segoe UI typography with Font Awesome icons, is responsive, and optimized for various devices.

### Technical Implementations
- **User Authentication**: Secure login/registration with Flask-Login and password hashing.
- **Data Management**: Individual and bulk (CSV) registration for donors and recipients with data validation. Required fields: Age, Gender, Blood Group, HLA Typing, Medical Conditions (Diabetes, Hypertension).
- **Machine Learning Engine**: A Random Forest Classifier (100 trees) predicts compatibility using 12 engineered features, including HLA match, blood compatibility, organ-specific storage freshness (calculated via `(1 - storage_hours / max_hours) × 100`), gender compatibility (weighted scoring considering size matching), GPS distance, age difference, and medical risk. It handles missing data intelligently and retrains automatically.
- **Real-Time Location**: Secure API endpoints use browser geolocation and Leaflet.js for interactive map-based location selection, storing coordinates and calculating distances with `geopy`.
- **Automatic Model Retraining**: A background threading system automatically retrains the ML model upon data changes, using debouncing and smart queue management.
- **Interactive Dashboard**: Provides system statistics, organ distribution, and quick actions.
- **Enhanced Compatibility Matching**: Comprehensive matching display with 12 detailed columns:
  1. **Donor ID** - Unique donor identifier with blue badge
  2. **Donor Name** - Full name with blood group and organ type
  3. **Recipient ID** - Unique recipient identifier with green badge
  4. **Recipient Name** - Full name with blood group and organ needed
  5. **Blood Compatibility** - Yes/No badge indicating ABO compatibility
  6. **HLA Match Score** - Percentage match (0-100%) with color coding
  7. **Storage Score** - Organ freshness score (0-100) based on storage hours
  8. **Urgency Level** - Recipient urgency (1-10 scale) with color-coded badges
  9. **Donor Medical Conditions** - Display of Diabetes, Hypertension, Smoking, Alcohol status
  10. **Recipient Medical Conditions** - Display of Diabetes, Hypertension status
  11. **Distance** - GPS distance between donor and recipient in kilometers
  12. **Final Compatibility** - ML-predicted match percentage with visual indicators
  
  Medical conditions and location data are used internally by the ML model for training and contribute to the final compatibility score.
- **Advanced Model Evaluation**: Comprehensive ML metrics including confusion matrix heatmap, ROC curve with AUC, classification report, and feature importance analysis.
- **Model Configuration**: Allows customization of Random Forest parameters (n_estimators, max_depth, min_samples_split, min_samples_leaf) with validation and immediate retraining.

### Feature Specifications
- **Login/Registration**: Secure authentication and session management.
- **Donor/Recipient Forms**: Capture medical, genetic, demographic (age, gender), and geographical data with interactive maps. All fields for Age, Gender, Blood Group, HLA Typing, and Medical Conditions are required.
- **CSV Bulk Upload**: Supports large-scale data imports with templates and validation. Skips rows missing required fields (Age, Gender, Blood Group, HLA Typing).
- **Location Sharing**: Interactive map selection and "Get Current Location" functionality. Displays geodesic distances between donor-recipient pairs.
- **Matches Page**: Comprehensive compatibility matching display showing donor/recipient names, blood compatibility status, HLA match percentage, storage score, urgency level, medical conditions, GPS distance, and final compatibility score.
- **Evaluate Page**: Visualizes ML performance metrics with Chart.js.
- **Settings Page**: Adjusts Random Forest hyperparameters and triggers model retraining.
- **Logs Page**: Terminal-style interface displaying chronological, color-coded system logs with filtering and database persistence.

### System Design Choices
- **Configuration Management**: Environment-based system (`config.py`) for Development, Production, and Testing, enforcing mandatory `SESSION_SECRET` and `DATABASE_URL` in production.
- **Database**: PostgreSQL for production (Replit's built-in service), with SQLite fallback for local development. Uses connection pooling for performance.
- **Database Schema**: Dedicated tables for Users, Donors, Recipients, MatchHistory, and SystemLog, capturing comprehensive attributes. Required fields for Donors and Recipients: name, age, gender, blood_group, hla_typing, diabetes, hypertension, plus organ_type for donors and organ_needed for recipients.
- **ML Feature Engineering**: Carefully selected medically relevant features for compatibility prediction.
- **Project Structure**: Production-ready file organization with clear separation of concerns.
- **System Logs**: Chronological, color-coded system events stored in the database for persistence.
- **Security**: Mandatory `SESSION_SECRET` in production, secure password hashing, CSRF protection, and proper session management.

## External Dependencies
- **Flask 3.0.0**: Web framework
- **Flask-Login 0.6.3**: User session management
- **SQLAlchemy**: Database ORM
- **psycopg2-binary**: PostgreSQL adapter
- **scikit-learn 1.3.2**: Machine learning library
- **pandas 2.1.3**: Data processing
- **numpy 1.26.2**: Numerical operations
- **geopy 2.4.1**: Geodesic distance calculations
- **Bootstrap 5**: Frontend UI framework
- **Chart.js**: Data visualization
- **Font Awesome**: Icon library
- **Leaflet.js 1.9.4**: Interactive map library