An AR-powered mobile application that gamifies urban cleanup through real-time object detection, tracking, and reward systems. Transform waste management into an engaging, competitive experience with ML-powered categorization and social features.
⚠️ Platform Status: Currently tested and verified on Android only. iOS support exists in code but is untested.
- AR Object Detection: Real-time ML Kit-powered object detection with colored overlays
- Smart Categorization: Advanced waste categorization system with 4 categories
- QR Code Scanning: Bin identification and validation system
- Inventory Management: Track picked-up items with cloud synchronization
- Proximity Detection: GPS-based bin detection within 10m radius
- Disposal Validation: Reward system for proper waste disposal
- Points & Achievements: Category-based scoring with multipliers and streaks
- Leaderboards: Real-time competition with time-based rankings
- Social Sharing: Generate and share achievement cards
- Deep Linking: Email verification and social sharing integration
- User Profiles: Track personal stats and environmental impact
- Interactive Maps: Bin locations and cleanup hotspots
- Bin Matching: Intelligent matching of detected objects to nearby bins
- Location Services: Comprehensive GPS and geofencing capabilities
- Supabase Integration: Full backend with authentication and real-time sync
- Google Sign-In: OAuth integration with platform-specific configuration
- Offline Support: Local storage with sync
- EcoGems (Recycle): Green
#4CAF50- Plastic, metal, paper, glass - BioShards (Organic): Light Green
#8BC34A- Food waste, plant matter - TechCores (E-waste): Orange
#FF9800- Electronics, batteries, devices - ToxicVials (Hazardous): Pink
#E91E63- Chemicals, paint, medical waste
- Framework: Flutter 3.24.0+ with Dart 3.9.0+
- State Management: Riverpod with code generation
- Navigation: GoRouter with declarative routing
- Backend: Supabase (Auth, Database, Storage, Real-time)
- ML/AR: Google ML Kit for object detection
- Maps: Google Maps Flutter integration
- Theme: Material 3 with environmental color palette
lib/core/services/
├── auth/ # Authentication & user management
│ ├── auth_service.dart # Main authentication service
│ └── supabase_config_service.dart # Supabase configuration
├── business/ # Business logic services
│ ├── inventory_service.dart # User inventory management
│ └── pickup_service.dart # Pickup detection and tracking
├── camera/ # Camera, AR, and ML detection
│ ├── qr_bin_service.dart # QR code scanning
│ ├── disposal_handling_service.dart # Disposal validation (simplified, no hand tracking)
│ └── camera_resource_manager.dart # Camera lifecycle management
├── data/ # Database and storage
│ ├── database_service.dart # Supabase database operations
│ ├── sync_service.dart # Cloud synchronization
│ ├── local_storage_service.dart # Local data persistence
│ └── data_migration_service.dart # Schema migrations
├── location/ # Location and mapping
│ ├── location_service.dart # GPS and geolocation
│ ├── bin_location_service.dart # Bin proximity detection
│ └── bin_matching_service.dart # Object-to-bin matching
├── social/ # Social and sharing features
│ ├── leaderboard_service.dart # Competition rankings
│ ├── social_sharing_service.dart # Achievement sharing
│ └── deep_link_service.dart # Deep link handling
└── platform/ # Platform-specific implementations
├── hand_tracking_service.dart # Gesture recognition
└── platform_optimizer.dart # Performance optimization
- Flutter SDK (>=3.24.0)
- Dart SDK (>=3.9.0)
- Android Studio for Android development (primary platform)
- Supabase account (optional - app runs in demo mode without)
📱 Platform Note: This app has been tested and verified on Android devices only. While iOS code exists, it has not been tested and may require additional work.
-
Clone and Setup
git clone <repository-url> cd cleanclik make setup # Installs dependencies and generates code
-
Environment Configuration (Optional)
cp .env.example .env # Edit .env with your Supabase credentials -
Run the App
flutter run # Or use the Makefile make test # Run all tests
# Setup and dependencies
make setup # Install dependencies and generate code
make clean # Clean build artifacts
# Testing
make test # Run all tests
make test-unit # Unit tests only
make test-widget # Widget tests only
make test-integration # Integration tests only
make coverage # Generate coverage report
# Code quality
make analyze # Run Flutter analyzer
make format # Format Dart code
make check # Run all quality checks
# Riverpod code generation
make generate # Generate provider code
make watch-generate # Watch for changes# Development builds (Android)
flutter run --debug
flutter run -d <android_device_id>
# Production builds (Android - untested)
flutter build apk --release
# iOS builds (untested - contributions welcome)
flutter build ios --release
# With environment variables
flutter build apk --dart-define=SUPABASE_URL="your-url"CleanClik supports both full functionality with Supabase and demo mode:
# Required for full functionality
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_KEY=your-publishable-key
# Optional for Google Sign-In (Removed from UI)
GOOGLE_WEB_CLIENT_ID=your-web-client-id.googleusercontent.com
GOOGLE_IOS_CLIENT_ID=your-ios-client-id.googleusercontent.comThe app uses Supabase with the following tables:
- users: User profiles with points and levels
- inventory: User's collected items with metadata
- achievements: Unlocked achievements and progress
- category_stats: Per-category statistics and totals
CAMERA- AR object detection and QR scanningACCESS_FINE_LOCATION- Bin proximity detectionACCESS_COARSE_LOCATION- General location servicesINTERNET- Supabase connectivity
- AR object detection with ML Kit
- Camera resource management
- Location services and GPS
- Supabase authentication and database
- Google Sign-In integration
NSCameraUsageDescription- AR scanning functionalityNSLocationWhenInUseUsageDescription- Location-based featuresNSPhotoLibraryUsageDescription- Achievement sharing
🚨 iOS Status: While iOS code is implemented, it has not been tested on actual devices. Contributions are welcome to test and improve iOS compatibility.
test/
├── unit/ # Service and model unit tests (95% coverage)
├── widget/ # UI component tests with golden files
├── integration/ # End-to-end user flow tests
└── golden/ # Visual regression tests
- Unit Tests: All services and business logic
- Widget Tests: UI components and screens
- Integration Tests: Complete user workflows
- Golden Tests: Visual regression testing
- Performance Tests: ML detection and AR performance
- Target: 90%+ code coverage
- Automated: CI/CD integration with coverage reports
- Analysis: Detailed coverage analysis with
make coverage-analyze
- Environment Setup Guide - Detailed configuration instructions
- Supabase Setup - Database and authentication setup
- Test Organization - Testing strategy and conventions
- Testing Guide - How to write and run tests
# Core Framework
flutter: ">=3.24.0"
dart: "^3.9.0"
# State Management & Navigation
flutter_riverpod: ^2.6.1
riverpod_annotation: ^2.6.1
go_router: ^14.6.2
# Backend & Authentication
supabase_flutter: ^2.8.2
google_sign_in: ^6.2.1
# Camera & ML
camera: ^0.11.0+2
google_mlkit_object_detection: ^0.12.0
qr_code_scanner_plus: ^2.0.10+1
# Location & Maps
geolocator: ^12.0.0
flutter_map: ^7.0.2
# Development Tools
build_runner: ^2.4.13
riverpod_generator: ^2.6.2
mockito: ^5.4.4
golden_toolkit: ^0.15.0We welcome contributions! This project was entirely generated using Kiro, any contributions are welcome to improve, test, and expand the codebase.
- Code Deletion / Refactoring: Identify and remove unused or redundant code, and refactor existing code for clarity and maintainability.
- iOS Testing & Fixes: Test the app on iOS devices and fix any platform-specific issues
- Performance Optimization: Improve AR detection performance on various devices
- UI/UX Improvements: Enhance the user interface and experience
- Feature Enhancements: Add new gamification features or improve existing ones
- Bug Fixes: Identify and fix issues in the current implementation
- Documentation: Improve documentation and add tutorials
- Services: Domain-organized in
lib/core/services/ - Models: Data structures in
lib/core/models/ - UI: Feature-organized in
lib/presentation/ - Tests: Mirror source structure in
test/
- Clean Architecture: Separation of concerns with service layers
- Dependency Injection: Constructor injection via Riverpod
- Error Handling: Comprehensive error handling and logging
- Resource Management: Proper lifecycle management for cameras and streams
- Fork the repository
- Test the app on your Android device
- Identify areas for improvement
- Submit pull requests with your enhancements
- Help test iOS functionality
- iOS Testing & Compatibility: Verify and fix iOS functionality
- Performance Optimization: Improve AR detection on mid-range devices
- Bug Fixes: Address any issues found during testing
- Documentation: Improve setup guides and API documentation
- AR Enhancements: Improved object tracking and overlay precision
- Community Features: Team challenges and group competitions
- Analytics Dashboard: Detailed environmental impact metrics
- Offline Mode: Enhanced offline functionality with sync
- Multi-language: Internationalization support
- Accessibility: Enhanced accessibility features and voice guidance
- Cross-Platform Testing: Comprehensive iOS and Android testing
- Performance: Further ML optimization and caching strategies
- Testing: Expanded test coverage and automated UI testing
- CI/CD: Enhanced deployment pipeline and automated releases
- Monitoring: Real-time performance monitoring and crash reporting
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
CleanClik - Transforming urban cleanup through AR gamification 🌱📱
🤖 AI-Generated • 📱 Android-Tested • 🤝 Contributions Welcome
P.S. If this README claims the app can do something impossible like time travel or make perfect coffee, that's just the AI being creative. Please test everything yourself! ☕️🤖 contributions are welcome..