Professional grain hauling logistics and tracking solution
HaulPass is a farmer-first grain hauling efficiency application that reduces wait times at grain elevators through real-time queue intelligence and comprehensive haul tracking. By collecting GPS data, timing information, and farmer observations, HaulPass enables data-driven decisions about when to haul grain, ultimately saving farmers hours every week.
The Problem: Farmers waste 2-4 hours daily waiting in grain elevator lines without knowing queue lengths or wait times ahead of time.
The Solution: HaulPass collects farmer-side data (locations, routes, queue positions, timing) to provide real-time queue intelligence and predictive wait times. Unlike traditional elevator scheduling software, we start from the farmer's perspective to build trust and demonstrate value before enabling elevator-side features.
MVP (Version 1.0):
- 🚛 Complete Haul Tracking: Track entire grain hauling workflow from loading to unloading
- 📍 Single Favorite Elevator: Focus on one elevator to prevent data errors
- ⏱️ Phase-Based Timers: Separate timers for loading, driving, queuing, unloading, and return
- 👥 Queue Intelligence: Real-time queue positions cross-validated between farmers
- ⏳ Estimated Wait Times: Calculated from user averages and current queue
- 📊 Daily Summaries: Comprehensive stats at end of each hauling day
- 📈 Personal Analytics: Track efficiency metrics over time
Future Features:
- Multiple favorite elevators (2-3)
- Premium grain breakdown (weight, price, quality by grain type)
- Predictive recommendations (best times to haul)
- Historical pattern analysis
- Elevator scheduling integration
- Farm management tools (bin, field, combine tracking)
Visit: https://bushels.github.io/HaulPass
# Clone the repository
git clone https://github.com/Bushels/HaulPass.git
cd HaulPass
# Install dependencies
flutter pub get
# Generate required code
flutter packages pub run build_runner build
# Run on web (recommended for development)
flutter run -d chrome
# Or run on mobile
flutter run -d android # or ios- Frontend: Flutter 3.24 with Riverpod state management
- Backend: Supabase (Database, Auth, Real-time, Storage)
- Deployment: GitHub Pages with automated CI/CD
- State Management: Riverpod 2.x with code generation
- Routing: GoRouter for navigation
- PWA: Progressive Web App with offline capabilities
lib/
├── core/
│ ├── services/ # Core services (Supabase, Environment)
│ ├── config/ # Configuration (Web, App)
│ └── theme/ # App theming
├── data/
│ ├── models/ # Data models with JSON serialization
│ ├── repositories/ # Repository pattern implementation
│ └── providers/ # Riverpod providers
├── domain/
│ ├── entities/ # Business logic entities
│ ├── repositories/ # Repository interfaces
│ └── use_cases/ # Business logic use cases
└── presentation/
├── screens/ # UI screens
├── widgets/ # Reusable UI components
└── providers/ # State management
Create a .env file (see .env.example):
SUPABASE_URL=your_supabase_url_here
SUPABASE_ANON_KEY=your_anon_key_here
GOOGLE_MAPS_API_KEY=your_google_maps_key_here- Create a Supabase project at https://supabase.com
- Get your project URL and anon key from Settings > API
- Configure environment variables
- Set up database tables using the provided migration scripts
- Enable Google Maps SDK for Web in Google Cloud Console
- Generate API key with required permissions
- Add to environment variables
Every push to main branch automatically:
- ✅ Triggers GitHub Actions workflow
- 🔨 Builds optimized Flutter web app
- 📦 Packages PWA with offline support
- 🚀 Deploys to GitHub Pages
- 🌐 Makes available at https://bushels.github.io/HaulPass
Add these secrets in repository Settings > Secrets and variables > Actions:
SUPABASE_URL: Your Supabase project URLSUPABASE_ANON_KEY: Your Supabase anonymous key
# Build web version
flutter build web --release
# Deploy to gh-pages branch
flutter build web
cd build/web
git init
git add -A
git commit -m 'deploy'
git push -f <repo_url> master:gh-pages- Installable: Add to home screen on mobile/desktop
- Offline Support: Basic functionality without internet
- Push Notifications: Real-time alerts and updates
- Responsive Design: Optimized for all screen sizes
- App-like Experience: Standalone display mode
# Run all tests
flutter test
# Run tests with coverage
flutter test --coverage
# Run integration tests
flutter drive --target=test_driver/app.dart
# Test web version
flutter test -d chrome- Web Build Size: ~12MB (optimized)
- Load Time: <3 seconds on average connection
- Lighthouse Score: 95+ (Performance, Accessibility, Best Practices)
- PWA Rating: 100/100 (Manifest, Service Worker)
- ✅ No hardcoded API keys
- ✅ Environment variable validation
- ✅ Secure Supabase integration
- ✅ HTTPS enforced in production
- ✅ Content Security Policy headers
- ✅ XSS protection enabled
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Extended user onboarding (farm, binyard, truck details)
- Complete haul workflow implementation (7 phases)
- Haul session state machine
- Timer display with color coding
- Single favorite elevator selection
- Queue entry and position tracking
- Cross-validation between users
- Wait time calculation algorithm
- Real-time queue updates
- Notification system
- Personal analytics dashboard
- Daily summary generation
- Historical pattern analysis
- Performance optimization
- Production launch preparation
See GAP_ANALYSIS_AND_ROADMAP.md for detailed implementation plan
Use GitHub Issues with:
- Clear description of the issue
- Steps to reproduce
- Expected vs actual behavior
- Environment details
- Screenshots if applicable
- 📖 Setup Guide - Detailed setup instructions
- 🎯 Vision & Specification - Complete product vision and technical spec
- 📊 Gap Analysis & Roadmap - Implementation roadmap and priorities
- 🏗️ Architecture - System design
- 🔄 Data Flow - Data handling and privacy
- 👥 User Journey - User experience flow
This project is licensed under the MIT License - see the LICENSE file for details.
- Flutter team for the amazing framework
- Supabase for the backend-as-a-service platform
- Riverpod team for excellent state management
- GitHub for hosting and CI/CD capabilities
Built with ❤️ for the grain hauling industry