🫁 Lungora - AI-Powered Lung Health Assistant

🫁 Empowering Health Through AI Technology 🚀

Revolutionary mobile app for intelligent lung health monitoring and medical consultation

🚧 Currently in Beta Version 🚧

📚 Table of Contents

📱 Overview
✨ Key Features
🏗️ Architecture & Tech Stack
📸 App Workflows
🚀 Getting Started
📁 Project Structure
🔧 Configuration
🌟 Features in Detail
🛡️ Security & Privacy
📈 Performance
🤝 Contributing
📄 License
🔮 Roadmap

📱 Overview

Lungora is an innovative Flutter-based mobile application that revolutionizes lung health monitoring through artificial intelligence. The app combines cutting-edge AI technology with user-friendly design to provide comprehensive X-ray analysis, doctor consultations, and personalized health tracking.

🎥 Live Demo

🎯 Mission

To make lung health monitoring accessible, accurate, and convenient for everyone through the power of AI and mobile technology.

📊 Project Status

🔨 Development Stage: Beta Testing Phase
📱 Platform Support: Android & iOS (Flutter)
🚀 Public Release: Coming Soon
👥 Team Size: Active development team
📈 Progress: Core features implemented
🔄 Future Enhancements: Planned features and improvements

✨ Key Features

🤖 AI-Powered Diagnostics Smart X-Ray Analysis - Upload chest X-rays for instant AI diagnosis Disease Detection - COVID-19, Pneumonia, Normal classification High Accuracy - Advanced ML algorithms for reliable predictions Image Processing - Automatic validation and cropping tools	👨‍⚕️ Doctor Consultation Location-Based Search - Find nearby healthcare providers Smart GPS Integration - Automatic location detection Comprehensive Profiles - Detailed doctor information Direct Communication - Contact doctors seamlessly
🔐 Security & Authentication Secure Login/Register - Email and password authentication OTP Verification - Two-factor authentication Password Management - Reset and change functionality Profile Management - Complete user data control	📊 Health Monitoring Real-time Analysis - Instant AI-powered diagnosis Detailed Reports - Comprehensive health insights Image Validation - Quality check for uploaded X-rays

⚙️ Additional Features

🎨 Theme Customization - Light/Dark mode support
🔒 Privacy Controls - Granular data management
🌍 Multi-Language - Localization support (planned)
📱 Responsive Design - Works perfectly on all screen sizes

🔮 Coming Soon Features

📜 Scan History - Track and review all previous X-ray analyses
🔔 Smart Notifications - Customizable push notifications and health reminders
📊 Progress Tracking - Monitor health improvements over time
📈 Analytics Dashboard - Detailed health insights and trends

🏗️ Architecture & Tech Stack

Frontend Framework

graph TD
    A[Flutter] --> B[Dart Language]
    A --> C[Material Design]
    A --> D[Cross-Platform]
    B --> E[BLoC Pattern]
    E --> F[State Management]
    E --> G[Cubit Implementation]

Technology	Purpose	Version
Flutter	Cross-platform mobile framework	^3.0.0
Dart	Programming language	Latest
BLoC (Cubit)	State management pattern	^8.1.3
Go Router	Advanced navigation system	^12.1.1
ScreenUtil	Responsive UI design	^5.9.0

Backend Integration

🌐 REST APIs - Clean and scalable API architecture
📡 Dio HTTP Client - Advanced networking with interceptors
🔑 JWT Authentication - Secure token-based sessions
📤 FormData Handling - Multipart file uploads for images

AI & Machine Learning

🧠 Custom AI Model - Trained specifically for lung disease detection
🖼️ Image Processing - Advanced preprocessing and validation
⚡ Real-time Analysis - Fast and accurate predictions
📏 Quality Validation - File size and format checking

Services & Permissions

📍 Location Services - GPS integration with permission handling
📷 Camera Integration - Native camera and gallery access
🔒 Secure Storage - Encrypted local data storage
🌐 Network Security - HTTPS and certificate pinning

📸 App Workflows

🔐 Authentication Flow

📱 App Launch → 🔐 Login/Register → 📧 OTP Verification → ✅ Dashboard Access

🫁 X-Ray Analysis Workflow

📷 Capture/Upload Image → ✂️ Crop & Validate Quality → 🤖 AI Processing & Analysis → 📊 Display Results & Recommendations → 💾 Generate & Save Medical Report

👨‍⚕️ Doctor Consultation Flow

📍 Location Request → 🗺️ Find Nearby Doctors → 👤 View Profiles & Reviews → 📞 Contact/Book Appointment

⚙️ Settings & Profile Flow

👤 Profile Access → ✏️ Edit Personal Information → 🔒 Security Settings → 💾 Save Changes

🔮 Future Workflows (Coming Soon)

📜 History Management Flow

📊 Dashboard → 📜 View Scan History → 🔍 Search & Filter Results → 📈 Compare Previous Scans → 📤 Export Reports

🔔 Notification System Flow

⚙️ Settings → 🔔 Notification Preferences → 📅 Set Health Reminders → 🔄 Sync with Calendar → 📱 Receive Smart Alerts

🚀 Getting Started

📋 Prerequisites

Flutter SDK (Latest stable version)
Dart SDK (Latest version)
IDE: Android Studio / VS Code / IntelliJ
Git for version control
Android/iOS Emulator or physical device

🔧 Installation Steps

📥 Clone the Repository

git clone https://github.com/omarAbdullahMoharam/lungora.git
cd lungora

📦 Install Dependencies

flutter pub get

🔧 Configure API Endpoints

// lib/core/helpers/api_services.dart
const String baseUrl = "YOUR_API_BASE_URL";

📱 Android Permissions Setup

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />

🍎 iOS Permissions Setup

<!-- ios/Runner/Info.plist -->
<key>NSCameraUsageDescription</key>
<string>This app needs camera access to capture X-ray images</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to find nearby doctors</string>

6. 🔧 Environment Configuration

# Copy the example environment file
cp .env.example .env

Create a file named .env.example in the root of your project and add the following:

OPENROUTER_API_KEY=your_api_key_here
MODEL_VERSION=your_model
API_ENDPOINT=chat/completions
BASE_URL=https://openrouter.ai/api/v1

7. ▶️ Run the Application

flutter run

📁 Project Structure

📦 lungora/
├── 📱 lib/
│   ├── 🎯 core/
│   │   ├── 🔧 helpers/
│   │   │   ├── 🌐 api_services.dart          # API endpoints
│   │   │   ├── 📍 location_service.dart       # GPS & permissions
│   │   │   ├── 📊 custom_snackbar.dart       # UI feedback
│   │   │   └── 💾 cache_helper.dart          # Local storage
│   │   ├── 🎨 utils/
│   │   │   ├── 🧭 app_router.dart            # Navigation
│   │   │   ├── 🎭 styles.dart                # UI themes
│   │   │   ├── 🔗 dependency_injection.dart  # DI container
│   │   │   └── 📐 constants.dart             # App constants
│   │   └── 🧩 widgets/
│   │       ├── 🔘 custom_elevated_button.dart
│   │       ├── 📝 custom_text_field.dart
│   │       └── 🔄 loading_widget.dart
│   ├── 🏠 features/
│   │   ├── 🔐 Auth/
│   │   │   ├── 📊 data/
│   │   │   │   ├── 🗂️ models/
│   │   │   │   └── 🏛️ repos/
│   │   │   ├── 🎭 presentation/
│   │   │   │   ├── 👁️ view/
│   │   │   │   ├── 🧠 view_model/
│   │   │   │   └── 🧩 widgets/
│   │   │   └── 🎯 domain/
│   │   ├── 👨‍⚕️ doctor/
│   │   │   ├── 📊 data/
│   │   │   ├── 🎭 presentation/
│   │   │   └── 🎯 domain/
│   │   ├── 🔍 Scan/
│   │   │   ├── 📊 data/
│   │   │   │   ├── 🗂️ models/
│   │   │   │   │   └── 🤖 ai_model_response.dart
│   │   │   │   └── 🏛️ repos/
│   │   │   ├── 🎭 presentation/
│   │   │   │   ├── 👁️ view/
│   │   │   │   ├── 🧠 view_model/
│   │   │   │   └── 🧩 widgets/
│   │   │   │       ├── 🖼️ build_image_preview.dart
│   │   │   │       ├── ⚠️ build_warning_banner.dart
│   │   │   │       └── 📋 build_selected_image_title.dart
│   │   │   └── 🎯 domain/
│   │   └── ⚙️ Settings/
│   │       ├── 📊 data/
│   │       ├── 🎭 presentation/
│   │       └── 🎯 domain/
│   └── 🎯 main.dart
├── 🎨 assets/
│   ├── 🖼️ images/
│   ├── 🎭 icons/
│   └── 🔤 fonts/
├── 🤖 android/
├── 🍎 ios/
└── 📝 pubspec.yaml

🔧 Configuration

🌐 API Endpoints Configuration

// lib/core/helpers/api_services.dart
abstract class ApiServices {
  // Authentication
  @POST("api/Auth/Login")
  Future<AuthResponse> login(@Body() Map<String, dynamic> body);
  
  @POST("api/Auth/Register")
  Future<AuthResponse> register(@Body() Map<String, dynamic> body);
  
  @POST("api/Auth/VerifyOTP")
  Future<AuthResponse> verifyOTP(@Body() Map<String, dynamic> body);
  
  // AI Model
  @POST("api/ModelAI/AI_Model")
  Future<AiModelResponse> getAIModel(@Part() FormData formData);
  
  // Doctor Services
  @GET("api/Doctor/GetAllDoctors")
  Future<DoctorsResponse> getAllDoctors();
  
  // User Management
  @GET("api/Auth/GetDataUser")
  Future<UserDataResponseModel> getUserData(@Header("Authorization") String token);
}

📦 Dependencies (pubspec.yaml)

dependencies:
  flutter: ^3.0.0
  
  # State Management
  flutter_bloc: ^8.1.3
  
  # Navigation
  go_router: ^12.1.1
  
  # Networking
  dio: ^5.3.2
  retrofit: ^4.0.3
  
  # Image Handling
  image_picker: ^1.0.4
  image_cropper: ^5.0.1
  
  # Permissions
  permission_handler: ^11.0.1
  
  # Location
  geolocator: ^9.0.2
  
  # UI & Responsiveness
  flutter_screenutil: ^5.9.0
  flutter_svg: ^2.0.7
  
  # Utilities
  fluttertoast: ^8.2.2
  shared_preferences: ^2.2.0
  
dev_dependencies:
  flutter_test: ^3.0.0
  build_runner: ^2.4.6
  retrofit_generator: ^8.0.4
  json_annotation: ^4.8.1
  json_serializable: ^6.7.1

🌟 Features in Detail

🤖 AI-Powered X-Ray Analysis

Click to expand detailed features

📋 Capabilities

Multi-Disease Detection: COVID-19, Pneumonia, Normal lung classification
High Accuracy Model: Custom-trained AI with medical imaging datasets
Real-time Processing: Analysis completed in seconds
Quality Validation: Automatic image quality assessment

🔧 Technical Implementation

// Example AI Model Integration
Future<AiModelResponse> analyzeXRay(File imageFile) async {
  final formData = FormData.fromMap({
    'image': await MultipartFile.fromFile(imageFile.path),
  });
  
  return await apiService.getAIModel(formData);
}

📊 Supported Classifications

COVID-19: Detection of COVID-related lung patterns
Pneumonia: Identification of pneumonia indicators
Normal: Healthy lung classification
Quality Check: Image clarity and positioning validation

📍 Location-Based Doctor Discovery

Click to expand location features

🗺️ Location Services

GPS Integration: Automatic location detection
Permission Handling: Smart permission request flows
Offline Support: Cached location data
Privacy Protection: Location data handled securely

👨‍⚕️ Doctor Discovery

Proximity Search: Find doctors within specified radius
Filter Options: Specialty, rating, availability
Detailed Profiles: Reviews, contact info, expertise
Direct Communication: Call, message, or book appointments

🔐 Security & Authentication

Click to expand security features

🛡️ Authentication Methods

Email/Password: Standard login with validation
OTP Verification: SMS/Email two-factor authentication
Biometric Login: Fingerprint/Face ID support (planned)
Social Login: Google/Facebook integration (planned)

🔒 Data Protection

JWT Tokens: Secure session management
Encrypted Storage: Local data encryption
API Security: HTTPS with certificate pinning
Privacy Controls: Granular data permissions

🛡️ Security & Privacy

🔐 Data Protection Measures

Security Layer	Implementation	Description
🌐 Network	HTTPS + Certificate Pinning	All API calls encrypted in transit
🔑 Authentication	JWT + Refresh Tokens	Secure session management
💾 Storage	AES Encryption	Local data encrypted at rest
🔒 Permissions	Runtime Requests	Granular permission controls
🛡️ Privacy	Data Minimization	Only necessary data collected

🔒 Privacy Compliance

GDPR Ready: European data protection compliance
HIPAA Considerations: Healthcare data handling best practices
User Control: Complete data management options
Transparency: Clear privacy policy and data usage

📈 Performance Optimizations

⚡ Speed & Efficiency

Optimization	Benefit	Implementation
🔄 Lazy Loading	Faster startup	Widget lazy initialization
💾 Smart Caching	Reduced API calls	Intelligent data caching
🖼️ Image Optimization	Faster loading	Automatic image compression
📱 Memory Management	Smooth performance	Efficient resource usage

📊 Performance Metrics

🚀 App Launch: < 3 seconds cold start
⚡ Navigation: Instant page transitions
🔄 API Response: < 2 seconds average
💾 Memory Usage: Optimized for low-end devices

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

🚀 Getting Involved

🍴 Fork the Repository

git fork https://github.com/omarAbdullahMoharam/lungora.git

🌿 Create Feature Branch

git checkout -b feature/amazing-new-feature

💾 Commit Changes

git commit -m "Add amazing new feature"

📤 Push to Branch

git push origin feature/amazing-new-feature

🔄 Open Pull Request

📝 Development Guidelines

🎯 Code Standards

📏 Style Guide: Follow official Dart/Flutter style guide
🏗️ Architecture: Use BLoC pattern for state management
🧪 Testing: Write unit and widget tests
📚 Documentation: Update docs for new features

🔍 Code Review Process

✅ Automated Tests: All tests must pass
👥 Peer Review: Minimum 2 reviewer approvals
🚀 Performance: No performance regressions
📱 Platform Testing: Test on both Android and iOS

🐛 Bug Reports

Use our issue template and include:

📱 Device Information
🔄 Steps to Reproduce
📊 Expected vs Actual Behavior
📸 Screenshots/Logs

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📋 License Summary

✅ Commercial Use: Allowed
✅ Modification: Allowed
✅ Distribution: Allowed
✅ Private Use: Allowed
❌ Liability: Not provided
❌ Warranty: Not provided

👥 Team & Credits

🏆 Core Team

Role	Responsibility	Skills
🎨 Mobile Lead	Flutter/Dart Development	UI/UX, State Management
🌐 Web Frontend Engineer	Web App Interface (Admin Dashboard)	React, HTML/CSS, JavaScript
🔧 Backend Engineer	API & Database	REST APIs, Security
🤖 AI Engineer	ML Model Development	TensorFlow, Medical Imaging
🎭 UI/UX Designer	User Experience	Design Systems, Prototyping
🔒 Security Expert	Data Protection	Encryption, Compliance

🙏 Acknowledgments

Medical Consultants for domain expertise
Flutter Community for packages and support
Open Source Contributors for making this possible

🔮 Roadmap & Future Plans

📅 Phase 1 - Beta Release (Current)

🤖 Core AI Model - Basic disease detection functionality
🔐 Authentication System - Secure login/register with OTP
📱 Mobile App - Flutter cross-platform application
👨‍⚕️ Doctor Discovery - Location-based doctor search
🖼️ Image Processing - X-ray upload, validation, and cropping
🧪 Beta Testing - Internal testing and bug fixes

📅 Phase 2 - Enhanced Core Features (Q2 2024)

📅 Phase 3 - Public Launch (Q3 2024)

🚀 App Store Release - Google Play & App Store deployment
🎯 Enhanced AI Accuracy - Improved model with larger medical dataset
📱 Progressive Web App - Web version for broader accessibility
🌍 Multi-Language Support - 5+ language translations
📈 Analytics Dashboard - Detailed health insights and metrics

📅 Phase 4 - Advanced Features (Q1 2025)

📱 Telemedicine Integration - Video consultations with doctors
⌚ Wearable Integration - Apple Watch/WearOS support
💊 Medication Tracking - Prescription and treatment management
🤝 Social Features - Community health discussions and support

📅 Phase 5 - Innovation (Q3 2025)

🥽 AR Visualization - 3D X-ray analysis with Augmented Reality
🧬 Genetic Integration - Personalized risk assessment based on genetics
🌐 Global Health Network - International doctor and hospital network
🤖 Advanced AI - Multi-modal medical analysis (X-ray + symptoms + history)

📞 Support & Contact

🛟 Getting Help

Channel	Purpose	Response Time
💬 WhatsApp Group	Join Community Chat	Real-time
🎮 Discord Server	Join Discord	Real-time
🐛 GitHub Issues	Bug reports & feature requests	24-48 hours
📧 Direct Contact	Technical discussions	Via Discord/WhatsApp

💬 Community Guidelines

🤝 Be Respectful: Treat all members with kindness
🎯 Stay On Topic: Keep discussions relevant to Lungora
🐛 Report Bugs: Use GitHub issues for bug reports
💡 Share Ideas: Feature suggestions are welcome
🚫 No Spam: Keep promotional content to minimum

🌐 Project Links

📂 GitHub Repository: omarAbdullahMoharam/lungora
📋 Project Board: GitHub Projects
🐛 Issue Tracker: GitHub Issues
📖 Documentation: GitHub Wiki

⭐ Star this Repository

If Lungora helped you or you find it interesting, please give it a star!

🚧 Development Status: Active Development 🚧

🔨 Currently in Beta Testing Phase
📱 Public Release Coming Soon

🫁 Made with ❤️ by the Lungora Team

"YOUR Health IS OUR MISSION"

🚀 Together, we're building the future of digital healthcare 🏥

Name		Name	Last commit message	Last commit date
Latest commit History 188 Commits
.vscode		.vscode
android		android
assets		assets
demo		demo
ios		ios
lib		lib
web		web
.env.example		.env.example
.gitignore		.gitignore
.metadata		.metadata
LICENSE		LICENSE
README.md		README.md
analysis_options.yaml		analysis_options.yaml
devtools_options.yaml		devtools_options.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml
splash.yaml		splash.yaml

Folders and files

Latest commit

History

Repository files navigation

🫁 Lungora - AI-Powered Lung Health Assistant

🫁 Empowering Health Through AI Technology 🚀

📚 Table of Contents

📱 Overview

🎥 Live Demo

🎯 Mission

📊 Project Status

✨ Key Features

🤖 AI-Powered Diagnostics

👨‍⚕️ Doctor Consultation

🔐 Security & Authentication

📊 Health Monitoring

⚙️ Additional Features

🔮 Coming Soon Features

🏗️ Architecture & Tech Stack

Frontend Framework

Backend Integration

AI & Machine Learning

Services & Permissions

📸 App Workflows

🔐 Authentication Flow

🫁 X-Ray Analysis Workflow

👨‍⚕️ Doctor Consultation Flow

⚙️ Settings & Profile Flow

🔮 Future Workflows (Coming Soon)

📜 History Management Flow

🔔 Notification System Flow

🚀 Getting Started

📋 Prerequisites

🔧 Installation Steps

6. 🔧 Environment Configuration

7. ▶️ Run the Application

📁 Project Structure

🔧 Configuration

🌐 API Endpoints Configuration

📦 Dependencies (pubspec.yaml)

🌟 Features in Detail

🤖 AI-Powered X-Ray Analysis

📋 Capabilities

🔧 Technical Implementation

📊 Supported Classifications

📍 Location-Based Doctor Discovery

🗺️ Location Services

👨‍⚕️ Doctor Discovery

🔐 Security & Authentication

🛡️ Authentication Methods

🔒 Data Protection

🛡️ Security & Privacy

🔐 Data Protection Measures

🔒 Privacy Compliance

📈 Performance Optimizations

⚡ Speed & Efficiency

📊 Performance Metrics

🤝 Contributing

🚀 Getting Involved

📝 Development Guidelines

🎯 Code Standards

🔍 Code Review Process

🐛 Bug Reports

📄 License

📋 License Summary

👥 Team & Credits

🏆 Core Team

🙏 Acknowledgments

🔮 Roadmap & Future Plans

📅 Phase 1 - Beta Release (Current)

📅 Phase 2 - Enhanced Core Features (Q2 2024)

📅 Phase 3 - Public Launch (Q3 2024)

📅 Phase 4 - Advanced Features (Q1 2025)

📅 Phase 5 - Innovation (Q3 2025)

📞 Support & Contact

🛟 Getting Help

💬 Community Guidelines

🌐 Project Links

⭐ Star this Repository

🚧 Development Status: Active Development 🚧

Packages