• Overview
• Features
• Screenshots
• Tech Stack
• Architecture
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Running the App
• Project Structure
• Database Schema
• Usage Guide
• Contributing
• License
• Contact

VeloGo is a comprehensive bike rental system that enables users to find, rent, and manage bike rentals through an intuitive mobile application. The app features real-time QR code scanning, duration-based pricing, live rental tracking with countdown timers, and seamless payment integration.

• 🔍 QR Code Scanning: Instant bike rental through QR code scanning
• ⏱️ Real-Time Tracking: Live countdown timers and rental status monitoring
• 💰 Flexible Pricing: Duration-based pricing from 30 minutes to 24 hours
• 📊 Usage Statistics: Track your rental history and spending
• 🗺️ Station Finder: Locate nearby bike stations on an interactive map
• 👤 User Profiles: Manage your account and view rental history

• Browse available bikes with detailed information
• Real-time availability status
• Bike specifications and images
• Station-based bike locations

• High-performance camera-based scanning
• Torch/flashlight support
• Front/back camera switching
• Automatic bike lookup and validation
• Error handling for invalid codes

• Flexible Duration Options:
  • 30 minutes - $2.50
  • 1 hour - $5.00
  • 2 hours - $10.00
  • 3 hours - $15.00
  • 4 hours - $20.00
  • 6 hours - $30.00
  • 12 hours - $60.00
  • 24 hours - $120.00
• Real-time countdown timer
• Elapsed time tracking
• Overtime notifications
• Automatic cost calculation
• Visual warnings for exceeded duration

• Integrated wallet system
• Balance validation before rental
• Automatic payment processing
• Transaction history
• Overtime charges

• Find nearby bike stations
• View available bikes per station
• Station details and operating hours
• Interactive map integration

• Secure authentication with Supabase
• Profile management
• Rental history
• Usage statistics
• Balance management

• Framework: Flutter 3.9.2
• Language: Dart 3.9.2
• State Management: Provider 6.1.5
• Navigation: GoRouter 17.0.0
• UI Components:
  • flutter_screenutil (Responsive design)
  • flutter_svg (Vector graphics)
  • flutter_spinkit (Loading animations)

• BaaS: Supabase 2.10.3
• Database: PostgreSQL (via Supabase)
• Authentication: Supabase Auth
• Storage: Supabase Storage

• mobile_scanner - QR code scanning
• shared_preferences - Local data persistence
• flutter_dotenv - Environment configuration
• cupertino_icons - iOS-style icons

VeloGo follows a clean, maintainable architecture pattern:

lib/
├── core/
│   ├── config.dart           # App configuration
│   ├── constant/             # Constants (routes, themes, images)
│   ├── functions/            # Utility functions
│   ├── service/              # Core services (Supabase, Storage)
│   └── utils/                # Helper utilities
├── data/
│   ├── model/                # Data models
│   └── service/              # Data services
├── providers/                # State management (Provider)
│   ├── auth_provider.dart
│   ├── bike_provider.dart
│   ├── rental_provider.dart
│   ├── profile_provider.dart
│   └── stats_provider.dart
├── views/                    # UI screens
│   ├── bike/                 # Bike-related screens
│   ├── home/                 # Home dashboard
│   ├── login/                # Authentication screens
│   ├── onboarding/           # App introduction
│   ├── profile/              # User profile
│   ├── rental/               # Rental management
│   ├── scan/                 # QR scanner
│   ├── splash/               # Splash screen
│   └── station/              # Station finder
├── shared/                   # Shared widgets and components
└── main.dart                 # App entry point

• Provider Pattern: State management across the app
• Repository Pattern: Data layer abstraction
• Service Layer: Business logic separation
• Widget Composition: Reusable UI components

Before you begin, ensure you have the following installed:

• Flutter SDK: Version 3.9.2 or higher

  flutter --version

• Dart SDK: Version 3.9.2 or higher
• Android Studio / Xcode (for mobile development)
• Git: For version control
• Supabase Account: For backend services

1. Clone the repository

   git clone https://github.com/LaithMahdi/VeloGo
   cd velogo

2. Install dependencies

   flutter pub get

3. Verify Flutter installation

   flutter doctor

1. Create a .env file in the project root:

   SUPABASE_URL=your_supabase_url
   SUPABASE_ANON_KEY=your_supabase_anon_key

2. Configure Supabase

   • Create a new Supabase project at supabase.com
   • Run the SQL scripts from supabase_rentals_table.sql in your Supabase SQL editor
   • Copy your project URL and anon key to the .env file

3. Set up assets

   • Place your logo images in assets/images/logo/
   • Place onboarding images in assets/images/onboarding/
   • Add custom fonts to assets/fonts/ (Poppins font family)

Android:

flutter run

iOS:

flutter run

Web:

flutter run -d chrome

Android APK:

flutter build apk --release

Android App Bundle:

flutter build appbundle --release

iOS:

flutter build ios --release

VeloGo/
├── android/                  # Android platform files
├── ios/                      # iOS platform files
├── web/                      # Web platform files
├── lib/                      # Main application code
│   ├── core/                 # Core functionality
│   ├── data/                 # Data layer
│   ├── providers/            # State management
│   ├── shared/               # Shared components
│   └── views/                # UI screens
├── assets/                   # Images, fonts, and resources
│   ├── fonts/
│   └── images/
├── test/                     # Unit and widget tests
├── .env                      # Environment variables (not in repo)
├── pubspec.yaml              # Dependencies and project metadata
├── RENTAL_SYSTEM_GUIDE.md    # Detailed rental system documentation
└── README.md                 # This file

User account information and wallet balance

Bike inventory with specifications and availability status

Physical locations where bikes can be picked up/returned

Active and completed rental records with pricing details

• start_rental(): Initialize a new rental session
• complete_rental(): Finalize rental and process payment
• calculate_rental_cost(): Real-time cost calculation
• get_active_rental(): Retrieve current active rental

For detailed schema and SQL scripts, see supabase_rentals_table.sql.

1. Sign Up/Login: Create an account or login with existing credentials
2. Browse Bikes: View available bikes at nearby stations
3. Scan QR Code: Use the scanner to scan a bike's QR code
4. Select Duration: Choose your rental duration (30 min - 24 hours)
5. Confirm Rental: Review pricing and confirm booking
6. Track Rental: Monitor remaining time and costs in real-time
7. Return Bike: Complete rental at any station and scan to return

See RENTAL_SYSTEM_GUIDE.md for detailed implementation documentation including:

• QR code scanner setup
• Rental flow implementation
• Database functions and triggers
• Provider usage examples
• Common troubleshooting

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/AmazingFeature

3. Commit your changes

   git commit -m 'Add some AmazingFeature'

4. Push to the branch

   git push origin feature/AmazingFeature

5. Open a Pull Request

• Follow Effective Dart guidelines
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed
• Run flutter analyze before committing

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

Project Maintainer: Laith Mahdi

• Flutter team for the amazing framework
• Supabase for the backend infrastructure
• Open source community for the excellent packages
• All contributors who have helped improve this project