> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Braian551/viax/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get Viax up and running in minutes with this step-by-step guide

# Quickstart Guide

Get the Viax platform running on your local machine or connect to the production backend in just a few steps.

## Prerequisites

Before you begin, ensure you have the following installed:

<CardGroup cols={2}>
  <Card title="Flutter SDK" icon="mobile">
    Version 3.35.3 or higher
  </Card>

  <Card title="Dart SDK" icon="code">
    Version 3.0 or higher
  </Card>

  <Card title="Git" icon="git">
    For cloning the repository
  </Card>

  <Card title="Code Editor" icon="laptop-code">
    VS Code or Android Studio recommended
  </Card>
</CardGroup>

## Choose Your Setup

You have two options to get started:

<Tabs>
  <Tab title="Production Backend (Fastest)">
    Connect directly to the production VPS - perfect for testing without local setup.
  </Tab>

  <Tab title="Local Development">
    Set up the full stack locally with Laragon - ideal for development and customization.
  </Tab>
</Tabs>

***

## Option A: Using Production Backend (Recommended for Testing)

This is the fastest way to get started. The backend is already deployed and running.

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/Braian551/viax.git
    cd viax
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    flutter pub get
    ```

    This downloads all required Flutter packages defined in `pubspec.yaml`.
  </Step>

  <Step title="Verify Configuration">
    The app is configured to use production by default. Check `lib/src/core/config/app_config.dart`:

    ```dart theme={null}
    static const String _envBaseUrl = String.fromEnvironment(
      'API_BASE_URL',
      defaultValue: 'http://76.13.114.194', // Production VPS
    );
    ```
  </Step>

  <Step title="Run the App">
    ```bash theme={null}
    # For Android emulator
    flutter run

    # For specific device
    flutter run -d <device-id>

    # List available devices
    flutter devices
    ```
  </Step>

  <Step title="Test the Connection">
    The app will automatically connect to:

    * **Backend URL**: `http://76.13.114.194`
    * **Database**: MySQL on VPS
    * **Email Service**: Gmail SMTP configured

    Try registering a new user to verify everything works!
  </Step>
</Steps>

<Tip>
  The production backend is fully functional with all features enabled. You can create users, register drivers, and test the complete flow.
</Tip>

***

## Option B: Local Development Setup

For development and customization, set up the complete stack locally.

<Steps>
  <Step title="Install Laragon">
    Download and install Laragon from [laragon.org](https://laragon.org/download/)

    Laragon includes:

    * Apache web server
    * MySQL database
    * PHP 8.3+
    * phpMyAdmin
  </Step>

  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/Braian551/viax.git
    cd viax
    ```
  </Step>

  <Step title="Set Up Backend">
    Copy the backend folder to Laragon's www directory:

    ```bash theme={null}
    # Windows
    xcopy /E /I backend C:\laragon\www\viax\backend

    # Or manually copy:
    # From: viax/backend
    # To: C:\laragon\www\viax\backend
    ```
  </Step>

  <Step title="Create Database">
    Open Laragon and start all services, then:

    1. Click **Database** button (opens phpMyAdmin)
    2. Create new database named `viax`
    3. Set charset to `utf8mb4_unicode_ci`
    4. Import the SQL file: `basededatos.sql`
  </Step>

  <Step title="Install PHP Dependencies">
    Open Laragon terminal and run:

    ```bash theme={null}
    cd C:\laragon\www\viax\backend
    composer install
    ```
  </Step>

  <Step title="Configure Flutter for Local">
    Update the base URL for your environment:

    ```bash theme={null}
    # For Android Emulator (10.0.2.2 maps to localhost)
    flutter run --dart-define=API_BASE_URL=http://10.0.2.2/viax/backend

    # For Physical Device (use your computer's IP)
    flutter run --dart-define=API_BASE_URL=http://192.168.1.XXX/viax/backend
    ```

    <Info>
      Find your IP with `ipconfig` (Windows) or `ifconfig` (Mac/Linux)
    </Info>
  </Step>

  <Step title="Verify Backend">
    Test the backend is working:

    ```bash theme={null}
    # In browser, visit:
    http://localhost/viax/backend/health.php

    # Should return:
    {"status":"ok"}
    ```
  </Step>

  <Step title="Run the App">
    ```bash theme={null}
    flutter pub get
    flutter run
    ```
  </Step>
</Steps>

<Note>
  For complete local setup instructions, see [Local Development Setup](/setup/local-development)
</Note>

***

## Verify Installation

### 1. Check Flutter Doctor

```bash theme={null}
flutter doctor -v
```

Ensure all checkmarks are green. Common issues:

* Android SDK not found → Install Android Studio
* iOS toolchain (Mac only) → Install Xcode

### 2. Test Backend Connectivity

The app automatically tests the backend connection on launch. Watch for:

✅ **Success indicators:**

* Login screen appears
* No connection errors
* Registration flow works

❌ **Connection issues:**

* "Could not connect to server" error
* Timeout messages
* Failed API calls

### 3. Test Key Features

<Tabs>
  <Tab title="Authentication">
    1. Tap **"Crear cuenta"** (Create account)
    2. Fill in user details
    3. Verify email with 6-digit code
    4. Login with credentials
  </Tab>

  <Tab title="Maps">
    1. After login, request a ride
    2. Map should load with your location
    3. Tap to select origin/destination
    4. Markers should appear correctly
  </Tab>

  <Tab title="Driver Features">
    1. Register as a driver
    2. Upload documents (license, vehicle)
    3. Wait for admin approval
    4. Toggle availability status
  </Tab>
</Tabs>

***

## Environment Configuration

Viax supports multiple environments through Dart defines:

```bash theme={null}
# Production (default)
flutter run

# Local Development
flutter run --dart-define=API_BASE_URL=http://10.0.2.2/viax/backend

# Staging (if you have a staging server)
flutter run --dart-define=API_BASE_URL=https://staging.viax.com
```

The app automatically detects the environment based on the URL:

* `localhost`, `10.0.2.2`, `192.168.*` → Development
* Contains `staging` → Staging
* Everything else → Production

***

## Building for Production

Once you've tested the app:

<CodeGroup>
  ```bash Android APK theme={null}
  # Build release APK
  flutter build apk --release

  # Output: build/app/outputs/flutter-apk/app-release.apk
  ```

  ```bash Android App Bundle theme={null}
  # Build for Google Play Store
  flutter build appbundle --release

  # Output: build/app/outputs/bundle/release/app-release.aab
  ```

  ```bash iOS theme={null}
  # Build for iOS (Mac only)
  flutter build ios --release
  ```
</CodeGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Refused / Timeout">
    **For Emulator:**

    * Use `10.0.2.2` instead of `localhost`
    * Verify backend is running: `http://localhost/viax/backend/health.php`

    **For Physical Device:**

    * Use your computer's local IP (e.g., `192.168.1.100`)
    * Ensure phone and computer are on the same WiFi network
    * Check firewall settings
  </Accordion>

  <Accordion title="Database Connection Failed">
    * Verify Laragon MySQL is running (green icon)
    * Check database credentials in `backend/config/database.php`:
      * Host: `localhost`
      * Username: `root`
      * Password: `root` (default Laragon)
      * Database: `viax`
    * Ensure database `viax` exists in phpMyAdmin
  </Accordion>

  <Accordion title="Maps Not Loading">
    * Check internet connection (maps require online access)
    * Verify Mapbox API key in env configuration
    * Check browser console for CORS errors
    * Ensure GPS permissions are granted
  </Accordion>

  <Accordion title="Email Verification Not Working">
    * Production backend uses configured Gmail SMTP
    * For local setup, configure PHPMailer in backend
    * Check spam folder for verification emails
    * Verify email service credentials in backend config
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Features" icon="compass" href="/features">
    Discover all platform capabilities
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/concepts/architecture">
    Understand the system design
  </Card>

  <Card title="Environment Setup" icon="gear" href="/setup/environment-configuration">
    Configure for different environments
  </Card>

  <Card title="Deploy" icon="rocket" href="/setup/production-deployment">
    Deploy to production
  </Card>
</CardGroup>

<Check>
  **Congratulations!** You now have Viax running. Start exploring the platform features and customizing for your needs.
</Check>