car_rental_app/rental_car_flutter_app_plan.md

# Rental Car Flutter App Development Plan

## 1. Project Overview

The goal is to build a cross-platform rental car application using Flutter. The app will allow customers to search for rental cars, view available vehicles, and submit booking requests.

The agency dashboard already exists as a web application. For the first mobile version, the existing web dashboard will be reused inside the Flutter app through a WebView instead of rebuilding the entire dashboard natively.

The app should work across:

- Android
- iOS
- Web
- Desktop, if needed later

Flutter will be used for the frontend because it supports multiple platforms from one codebase.

---

## 2. Main User Types

## 2.1 Customer

Customers are normal users who want to rent a car.

Customers should be able to:

- Open the app
- View the company logo on the home page
- Click the **Search your Car** button
- Enter pick-up location
- Enter drop-off location
- Select pick-up date and time
- Select drop-off date and time
- Select car type
- View available cars
- View car details
- Submit a booking request

## 2.2 Agency

Agencies are rental companies that already use the existing web dashboard.

Agencies should be able to:

- Click the **Agency** space on the home page
- Open the existing web dashboard inside the mobile app
- Sign in using existing agency credentials
- Manage cars
- Manage bookings
- Manage pricing
- Manage company information

---

## 3. MVP Strategy

The first version should not rebuild the agency dashboard in Flutter.

Instead, the Flutter app should:

- Build a native customer-facing rental search experience
- Use WebView to display the existing agency dashboard
- Keep customer and agency flows separate
- Avoid duplicating dashboard code too early

This keeps development faster, cheaper, and less likely to collapse under its own heroic ambition.

---

## 4. Home Page

## 4.1 Purpose

The home page should be simple, clean, and direct.

It should immediately give the user two choices:

1. Search for a rental car
2. Access the agency area

## 4.2 Home Page Elements

The home page should include:

- Company logo
- Main button labeled **Search your Car**
- Small clickable area labeled **Agency**
- Optional slogan under the logo
- Clean background
- Mobile-friendly layout

## 4.3 Home Page Layout

```text
------------------------------------------------
|                                              |
|              Company Logo                    |
|                                              |
|          Find your rental car                |
|                                              |
|        [ Search your Car ]                   |
|                                              |
|                                              |
|                 Agency                       |
|                                              |
------------------------------------------------
```

## 4.4 Home Page Actions

### Search your Car

When the user clicks **Search your Car**, the app opens the customer search screen.

### Agency

When the user clicks **Agency**, the app opens the existing web dashboard inside a Flutter WebView.

---

## 5. Customer Search Flow

## 5.1 Search Screen

After clicking **Search your Car**, the user should see a search form.

## 5.2 Search Fields

The search form should include:

- Pick-up location
- Drop-off location
- Pick-up date
- Pick-up time
- Drop-off date
- Drop-off time
- Car type selector

## 5.3 Car Types

Example car types:

- Economy
- Compact
- Sedan
- SUV
- Luxury
- Van
- Pickup Truck
- Electric
- Hybrid

## 5.4 Search Form Layout

```text
------------------------------------------------
| Search Your Car                              |
|                                              |
| Pick-up Location                             |
| [ Enter location ]                           |
|                                              |
| Drop-off Location                            |
| [ Enter location ]                           |
|                                              |
| Pick-up Date & Time                          |
| [ Select date ] [ Select time ]              |
|                                              |
| Drop-off Date & Time                         |
| [ Select date ] [ Select time ]              |
|                                              |
| Car Type                                     |
| [ Select car type ]                          |
|                                              |
| [ Search Cars ]                              |
------------------------------------------------
```

## 5.5 Validation Rules

The app should validate:

- Pick-up location is required
- Drop-off location is required
- Pick-up date is required
- Pick-up time is required
- Drop-off date is required
- Drop-off time is required
- Drop-off date/time must be after pick-up date/time
- Car type is required or defaults to **Any**
- Empty location strings should not be accepted

---

## 6. Search Results Page

## 6.1 Purpose

The search results page displays available cars based on the customer’s search criteria.

## 6.2 Car Card Information

Each car card should show:

- Car image
- Car name
- Car type
- Transmission type
- Fuel type
- Number of seats
- Price per day
- Agency name
- Availability status
- Button: **View Details**

## 6.3 Example Car Card

```text
------------------------------------------------
| [Car Image]                                  |
| Toyota Corolla                               |
| Sedan | Automatic | Gasoline                 |
| 5 Seats                                      |
| $45/day                                      |
| Agency: Fast Rent Cars                       |
| [ View Details ]                             |
------------------------------------------------
```

---

## 7. Car Details Page

## 7.1 Purpose

The car details page shows full information about a selected vehicle.

## 7.2 Details to Display

The page should include:

- Car images
- Car name
- Car type
- Brand
- Model
- Year
- Transmission
- Fuel type
- Number of seats
- Luggage capacity
- Price per day
- Deposit amount
- Mileage policy
- Insurance options
- Agency name
- Pick-up and drop-off policy
- Button: **Book Now**

---

## 8. Booking Flow

## 8.1 Booking Request

When the customer clicks **Book Now**, the app should open a booking form.

## 8.2 Booking Fields

The booking should include:

- Customer name
- Customer phone
- Customer email
- Selected car
- Pick-up location
- Drop-off location
- Pick-up date/time
- Drop-off date/time
- Total price
- Booking status

## 8.3 Booking Status Options

```text
Pending
Confirmed
Rejected
Cancelled
Completed
```

## 8.4 Payment Strategy

For the first version, online payment should be skipped unless it already exists in the current system.

Recommended MVP payment approach:

- Customer submits booking request
- Agency reviews booking
- Agency confirms availability
- Customer pays manually or through an external payment link

Online payment can be added later using:

- Stripe
- PayPal
- Square
- Local payment provider

Do not add payment processing too early. Payment systems look simple until refunds, disputes, taxes, and failed transactions arrive with knives.

---

## 9. Agency Dashboard Integration

## 9.1 Strategy

The agency dashboard already exists as a web application.

For version 1, the Flutter app should open the existing dashboard inside a WebView.

This avoids rebuilding the dashboard in Flutter and allows agencies to continue using the current system.

## 9.2 Agency Flow

```text
Home Page
→ Agency
→ WebView opens existing dashboard login page
→ Agency signs in
→ Existing company dashboard opens
→ Agency manages cars, bookings, pricing, and profile
```

## 9.3 Recommended MVP Flow

The simplest first version is:

1. User clicks **Agency**
2. Flutter opens `AgencyDashboardWebViewScreen`
3. WebView loads the existing web dashboard login page
4. Agency signs in using existing credentials
5. Agency uses the current dashboard inside the mobile app

## 9.4 Why This Is Better for MVP

Using WebView allows the app to:

- Reuse the existing dashboard
- Save development time
- Avoid duplicating business logic
- Avoid rebuilding agency management screens
- Keep agency operations consistent across web and mobile
- Launch faster

## 9.5 Risks

The existing dashboard must be tested carefully on mobile.

Potential risks:

- Dashboard may not be fully responsive
- Some buttons or tables may be hard to use on small screens
- Image upload may require WebView permissions
- File picker behavior may differ across Android and iOS
- Login sessions may expire unexpectedly
- Push notifications may not work through the web dashboard
- App store review may object if the app feels like only a wrapped website

## 9.6 MVP Decision

For version 1:

- Use WebView for the agency dashboard
- Do not rebuild the dashboard natively
- Test the dashboard on Android and iPhone
- Only rebuild dashboard parts in Flutter if WebView creates serious usability problems

---

## 10. Suggested Flutter Package for WebView

Use:

```yaml
webview_flutter: ^4.0.0
```

Example screen:

```dart
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

class AgencyDashboardWebViewScreen extends StatefulWidget {
  const AgencyDashboardWebViewScreen({super.key});

  @override
  State<AgencyDashboardWebViewScreen> createState() =>
      _AgencyDashboardWebViewScreenState();
}

class _AgencyDashboardWebViewScreenState
    extends State<AgencyDashboardWebViewScreen> {
  late final WebViewController controller;

  @override
  void initState() {
    super.initState();

    controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..loadRequest(
        Uri.parse('https://your-dashboard-url.com'),
      );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Agency Dashboard'),
      ),
      body: WebViewWidget(controller: controller),
    );
  }
}
```

Replace:

```text
https://your-dashboard-url.com
```

with the real dashboard URL.

---

## 11. Login Strategy

## 11.1 Recommended First Version

For MVP, let the existing dashboard handle login.

Flow:

```text
Agency clicks Agency
→ WebView opens dashboard login page
→ Agency logs in using existing credentials
→ Dashboard opens inside app
```

This avoids complicated token handoff between Flutter and the web dashboard.

## 11.2 More Advanced Future Version

Later, the Flutter app can have its own agency login screen.

Flow:

```text
Agency clicks Agency
→ Flutter sign-in screen
→ Authenticate agency
→ Generate secure session
→ Open dashboard already logged in
```

This requires secure authentication handling.

Do not pass permanent tokens in the URL.

Avoid:

```text
https://dashboard.com?token=abc123
```

Better options:

- Secure cookies
- OAuth redirect
- Backend-generated session
- Short-lived one-time login token
- Firebase custom token flow
- Supabase session handoff

---

## 12. Updated Screen List

## 12.1 Customer Screens

```text
HomeScreen
SearchCarScreen
SearchResultsScreen
CarDetailsScreen
BookingScreen
BookingConfirmationScreen
```

## 12.2 Agency Screens

```text
AgencyDashboardWebViewScreen
```

## 12.3 Optional Future Agency Screens

```text
NativeAgencySignInScreen
NativeAgencyDashboardScreen
ManageCarsScreen
AddCarScreen
EditCarScreen
ManageBookingsScreen
BookingDetailsScreen
AgencyProfileScreen
```

---

## 13. Suggested Flutter Project Structure

```text
lib/
│
├── main.dart
├── app.dart
│
├── core/
│   ├── constants/
│   ├── theme/
│   ├── routing/
│   ├── utils/
│   └── widgets/
│
├── features/
│   ├── home/
│   ├── car_search/
│   ├── car_details/
│   ├── booking/
│   └── agency_webview/
│
├── models/
│   ├── car_model.dart
│   ├── booking_model.dart
│   └── agency_model.dart
│
├── services/
│   ├── car_service.dart
│   ├── booking_service.dart
│   └── agency_service.dart
│
└── providers/
    ├── car_provider.dart
    └── booking_provider.dart
```

---

## 14. Routing Plan

Suggested routes:

```text
/
    HomeScreen

/search
    SearchCarScreen

/results
    SearchResultsScreen

/car/:carId
    CarDetailsScreen

/booking/:carId
    BookingScreen

/booking-confirmation
    BookingConfirmationScreen

/agency
    AgencyDashboardWebViewScreen
```

Future native agency routes:

```text
/agency/login
    NativeAgencySignInScreen

/agency/dashboard
    NativeAgencyDashboardScreen

/agency/cars
    ManageCarsScreen

/agency/bookings
    ManageBookingsScreen
```

---

## 15. Recommended Flutter Packages

## 15.1 State Management

Recommended:

```yaml
flutter_riverpod
```

Alternative options:

```yaml
provider
bloc
```

## 15.2 Navigation

Recommended:

```yaml
go_router
```

## 15.3 Forms and Validation

```yaml
flutter_form_builder
form_builder_validators
```

## 15.4 Date and Time

```yaml
intl
```

Flutter also includes built-in date and time pickers.

## 15.5 WebView

```yaml
webview_flutter
```

## 15.6 Images and UI

```yaml
cached_network_image
flutter_svg
google_fonts
```

---

## 16. Backend Recommendation

If the current web dashboard already has a backend, the Flutter app should connect to the same backend.

The customer search and booking flow should use the same data source as the existing dashboard.

This prevents duplicate data, mismatched bookings, and the kind of confusion that makes support teams age in dog years.

If no backend API is available yet, create one before building too much Flutter UI.

Recommended backend options:

- Existing dashboard backend
- Firebase
- Supabase
- Node.js API
- Laravel API

---

## 17. Database Design

If the current system already has these tables or collections, reuse them.

## 17.1 Agencies

```json
{
  "agencyId": "string",
  "companyName": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "logoUrl": "string",
  "createdAt": "timestamp",
  "isActive": true
}
```

## 17.2 Cars

```json
{
  "carId": "string",
  "agencyId": "string",
  "name": "Toyota Corolla",
  "brand": "Toyota",
  "model": "Corolla",
  "year": 2023,
  "type": "Sedan",
  "transmission": "Automatic",
  "fuelType": "Gasoline",
  "seats": 5,
  "doors": 4,
  "luggageCapacity": 2,
  "pricePerDay": 45,
  "depositAmount": 200,
  "description": "Clean and fuel-efficient sedan.",
  "imageUrls": [],
  "isAvailable": true,
  "createdAt": "timestamp"
}
```

## 17.3 Bookings

```json
{
  "bookingId": "string",
  "carId": "string",
  "agencyId": "string",
  "customerName": "string",
  "customerEmail": "string",
  "customerPhone": "string",
  "pickupLocation": "string",
  "dropoffLocation": "string",
  "pickupDateTime": "timestamp",
  "dropoffDateTime": "timestamp",
  "carType": "Sedan",
  "totalPrice": 180,
  "status": "Pending",
  "createdAt": "timestamp"
}
```

---

## 18. Security Requirements

Security rules must enforce:

- Agencies can only manage their own data
- Customers cannot access agency management features
- Public users can search available cars
- Booking creation must validate required fields
- Booking status changes must be restricted to agency users
- Dashboard sessions must be protected
- API keys must not be exposed inside the Flutter app

The WebView dashboard must use HTTPS.

Never load the dashboard over plain HTTP.

---

## 19. Rental Business Logic

## 19.1 Rental Duration

The app should calculate rental duration using pick-up and drop-off date/time.

Rules:

- Minimum rental duration is 1 day
- If the rental is less than 24 hours, charge 1 day
- If the rental includes partial days, round up to the next full day
- Drop-off date/time must be after pick-up date/time

Example:

```text
Pick-up: June 1, 10:00 AM
Drop-off: June 3, 2:00 PM

Rental duration = 3 days
```

## 19.2 Total Price

Basic formula:

```text
Total Price = Rental Days × Price Per Day
```

Future additions:

- Taxes
- Deposit
- Insurance
- Discount
- Late return fee
- Extra driver fee
- Delivery fee

---

## 20. MVP Feature List

## 20.1 Customer MVP

The customer side should include:

- Home page
- Search form
- Search results page
- Car details page
- Booking request form
- Booking confirmation page

## 20.2 Agency MVP

The agency side should include:

- Agency link on home page
- WebView dashboard screen
- Existing dashboard login
- Existing dashboard management tools

## 20.3 Backend MVP

The backend should support:

- Car listing retrieval
- Search/filtering
- Booking creation
- Agency dashboard data
- Secure agency access

---

## 21. Features to Avoid in Version 1

Do not include these in the first version unless they already exist and work:

- Native Flutter agency dashboard
- Online payment
- Coupons
- Loyalty points
- Live chat
- GPS tracking
- AI recommendations
- Complex analytics
- Multi-language support
- Push notifications

These features can come later. Early-stage apps usually fail because someone keeps adding “just one more thing” until the roadmap looks like a hostage note.

---

## 22. Development Phases

## Phase 1: Planning and Setup

- Confirm app name
- Prepare company logo
- Confirm existing dashboard URL
- Confirm backend/API access
- Create Flutter project
- Set up routing
- Set up theme
- Add WebView package

## Phase 2: Home Page

- Build home screen
- Add company logo
- Add **Search your Car** button
- Add small **Agency** space
- Connect buttons to routes

## Phase 3: Agency WebView

- Create `AgencyDashboardWebViewScreen`
- Load dashboard URL
- Test dashboard login
- Test dashboard responsiveness
- Test image upload
- Test Android behavior
- Test iOS behavior

## Phase 4: Customer Search UI

- Build search form
- Add pick-up location field
- Add drop-off location field
- Add date pickers
- Add time pickers
- Add car type dropdown
- Add validation

## Phase 5: Search Results

- Create car model
- Use fake data first
- Build car cards
- Build search results page
- Add filtering by car type and location

## Phase 6: Car Details

- Build car details page
- Display car image and details
- Add price information
- Add **Book Now** button

## Phase 7: Booking Flow

- Build booking form
- Calculate rental days
- Calculate total price
- Submit booking request
- Show booking confirmation

## Phase 8: Backend Integration

- Connect to existing backend or API
- Fetch real car data
- Submit real booking requests
- Confirm bookings appear in agency dashboard
- Test data consistency

## Phase 9: Testing

Test:

- Home page navigation
- Search form validation
- Search results filtering
- Car details page
- Booking creation
- WebView dashboard login
- Dashboard mobile responsiveness
- Dashboard image upload
- Android build
- iOS build
- Web build, if needed

## Phase 10: Deployment

- Prepare Android release
- Prepare iOS release
- Configure production backend
- Configure dashboard production URL
- Test final builds
- Prepare app store assets
- Submit to app stores

---

## 23. WebView Testing Checklist

Before accepting WebView as the final agency solution, test:

- Dashboard opens correctly
- Login works
- Logout works
- Session stays active properly
- Dashboard layout fits mobile screens
- Menu/navigation works on touch devices
- Tables are readable
- Forms are usable
- Add car works
- Edit car works
- Delete/archive car works
- Booking management works
- Image upload works
- File picker works
- Camera/gallery permissions work
- Keyboard does not cover form fields
- Back button behavior works on Android
- Dashboard uses HTTPS
- No sensitive token is exposed in the URL

---

## 24. Risks and Decisions

## Risk 1: Dashboard Not Mobile Responsive

If the existing dashboard does not work well on phone screens, the WebView approach may feel poor.

Decision:

Test first. Rebuild only the broken dashboard parts natively if needed.

## Risk 2: Authentication Complexity

Passing login sessions between Flutter and the web dashboard can become complicated.

Decision:

For MVP, let the web dashboard handle login inside WebView.

## Risk 3: Duplicate Data

If the mobile app uses a different backend from the dashboard, bookings and cars may become inconsistent.

Decision:

Use the same backend/API as the existing dashboard.

## Risk 4: App Store Review

If the app is only a website wrapper, app stores may reject it.

Decision:

Make the customer search and booking experience native Flutter. Use WebView only for the agency dashboard.

## Risk 5: Scope Creep

Trying to build customer app, native dashboard, payments, notifications, and analytics all at once will slow the launch.

Decision:

Build only the MVP first.

---

## 25. MVP Success Criteria

The MVP is successful when:

- Customer can open the app
- Customer can search for a car
- Customer can view car details
- Customer can submit a booking request
- Agency can open the dashboard inside the app
- Agency can sign in
- Agency can manage cars and bookings using the existing dashboard
- The same data appears correctly between the customer app and dashboard
- The app works on Android and iOS
- The WebView dashboard is usable on mobile

---

## 26. Recommended First Build Order

Build in this order:

1. Create Flutter project
2. Build home page
3. Add company logo
4. Add **Search your Car** button
5. Add **Agency** entry point
6. Add WebView dashboard screen
7. Test existing dashboard inside the app
8. Build search form
9. Build fake search results
10. Build car details page
11. Build booking form
12. Connect backend/API
13. Test booking flow with dashboard
14. Polish UI
15. Test Android and iOS
16. Deploy

---

## 27. Final MVP Scope

## Customer

- Home page
- Search form
- Search results
- Car details
- Booking request
- Booking confirmation

## Agency

- Agency button/link
- WebView dashboard
- Existing dashboard login
- Existing dashboard management

## Backend

- Existing dashboard backend if available
- Car data
- Booking data
- Agency data
- Secure dashboard access

---

## 28. Final Recommendation

Use Flutter for the customer-facing mobile app.

Use WebView for the existing agency dashboard in version 1.

Do not rebuild the agency dashboard natively until there is clear evidence that the WebView version is not good enough.

This approach reduces development time, protects the existing dashboard investment, and gets the app closer to launch without turning the project into a feature swamp.