> ## 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.

# User Roles & Permissions

> Understanding the different user types in Viax and their permissions

# User Roles & Permissions

Viax supports four distinct user roles, each with specific capabilities, permissions, and responsibilities within the platform.

## Role Overview

<CardGroup cols={2}>
  <Card title="Users" icon="user" color="#2196F3">
    Customers who request rides and deliveries
  </Card>

  <Card title="Drivers" icon="car" color="#4CAF50">
    Conductors who accept and fulfill service requests
  </Card>

  <Card title="Administrators" icon="shield" color="#FF9800">
    Platform managers with full system access
  </Card>

  <Card title="Companies" icon="building" color="#9C27B0">
    Organizations managing fleets of drivers
  </Card>
</CardGroup>

***

## Users (Customers)

### Role Description

Users are the primary customers of the platform who request transportation or delivery services.

### Registration Requirements

<Steps>
  <Step title="Basic Information">
    * Full name (nombre\_completo)
    * Email address (unique)
    * Phone number
    * Password (minimum 8 characters)
  </Step>

  <Step title="Email Verification">
    * 6-digit verification code sent to email
    * Code expires after 10 minutes
    * Must verify before accessing services
  </Step>

  <Step title="Optional Information">
    * Profile photo
    * Home address
    * Preferred payment methods
  </Step>
</Steps>

### Permissions & Capabilities

<Tabs>
  <Tab title="Trip Management">
    **Can:**

    * ✅ Request rides
    * ✅ Request package deliveries
    * ✅ Select pickup and dropoff locations
    * ✅ Choose vehicle type
    * ✅ View price estimates
    * ✅ Track active trips
    * ✅ Cancel pending requests
    * ✅ View trip history

    **Cannot:**

    * ❌ Accept trip requests
    * ❌ View other users' trips
    * ❌ Modify completed trips
  </Tab>

  <Tab title="Profile">
    **Can:**

    * ✅ Update personal information
    * ✅ Change password
    * ✅ Upload profile photo
    * ✅ Manage addresses
    * ✅ View account statistics
    * ✅ Delete account (with confirmation)

    **Cannot:**

    * ❌ Access admin features
    * ❌ Become a driver without separate registration
    * ❌ View system-wide data
  </Tab>

  <Tab title="Payments">
    **Can:**

    * ✅ Add payment methods
    * ✅ Set default payment
    * ✅ View payment history
    * ✅ Download receipts
    * ✅ Report payment issues

    **Cannot:**

    * ❌ Process refunds directly
    * ❌ View other users' payments
    * ❌ Modify pricing rules
  </Tab>

  <Tab title="Communication">
    **Can:**

    * ✅ Contact support
    * ✅ Chat with assigned driver (during trip)
    * ✅ Report problems
    * ✅ Rate drivers

    **Cannot:**

    * ❌ Contact drivers outside active trips
    * ❌ Send mass messages
    * ❌ Access admin support tickets
  </Tab>
</Tabs>

### User States

```sql theme={null}
enum estado_usuario {
  'activo',      -- Normal active user
  'suspendido',  -- Temporarily suspended
  'bloqueado'    -- Permanently blocked
}
```

**State Transitions:**

* `activo` → `suspendido`: Admin action (policy violation)
* `suspendido` → `activo`: Admin reinstates after review
* `activo` → `bloqueado`: Permanent ban (serious violations)

***

## Drivers (Conductors)

### Role Description

Drivers are service providers who accept trip requests and transport users or packages.

### Registration Requirements

<AccordionGroup>
  <Accordion title="Personal Information">
    * Full name matching ID documents
    * Email address (unique)
    * Phone number (verified)
    * Physical address
    * Date of birth (18+ years)
    * National ID number
  </Accordion>

  <Accordion title="Driver License">
    **Required Fields:**

    * License number
    * Issue date
    * Expiration date
    * License category/class
    * Issuing authority

    **Documents to Upload:**

    * Front photo of license (clear, readable)
    * Back photo of license
    * Must be valid (not expired)
  </Accordion>

  <Accordion title="Vehicle Information">
    * Vehicle make and model
    * Year of manufacture
    * License plate number
    * Vehicle color
    * Vehicle type (moto, carro, moto\_carga, carro\_carga)
    * Seating capacity

    **Vehicle Documents:**

    * Registration certificate
    * Insurance policy (valid)
    * Vehicle inspection certificate
    * Photos (front, back, sides, interior)
  </Accordion>

  <Accordion title="Additional Requirements">
    * Bank account for payments
    * Profile photo (professional)
    * Clean driving record
    * Pass background check (admin review)
    * Accept terms of service
  </Accordion>
</AccordionGroup>

### Verification Workflow

```mermaid theme={null}
graph LR
    A[Registration] --> B[Documents Uploaded]
    B --> C{Admin Review}
    C -->|Approved| D[Active Driver]
    C -->|Rejected| E[Resubmit]
    E --> B
    D --> F[Can Accept Trips]
```

### Verification States

```dart theme={null}
enum EstadoVerificacion {
  pendiente,    // Awaiting admin review
  en_revision,  // Currently being reviewed
  aprobado,     // Approved, can accept trips
  rechazado     // Rejected, must fix issues
}
```

### Driver Permissions

<Tabs>
  <Tab title="Trip Operations">
    **Can:**

    * ✅ View nearby trip requests (within 5km)
    * ✅ Accept trip requests
    * ✅ Decline trip requests
    * ✅ Navigate to pickup location
    * ✅ Start trip
    * ✅ Update trip status
    * ✅ Complete trip
    * ✅ Cancel trips (with valid reason)
    * ✅ View active trip details

    **Cannot:**

    * ❌ Accept trips while offline
    * ❌ Accept trips if not verified
    * ❌ Accept multiple trips simultaneously
    * ❌ Modify trip pricing
    * ❌ Cancel without penalty after certain point
  </Tab>

  <Tab title="Availability">
    **Can:**

    * ✅ Toggle online/offline status
    * ✅ Update GPS location automatically
    * ✅ Set working hours preferences
    * ✅ View demand heat maps

    **Automatic Status Changes:**

    * Goes offline when accepting a trip
    * Returns online after trip completion
    * Goes offline if GPS lost for 5+ minutes
    * Goes offline if app in background > 10 minutes
  </Tab>

  <Tab title="Earnings">
    **Can:**

    * ✅ View daily/weekly/monthly earnings
    * ✅ See earnings breakdown per trip
    * ✅ Track commission deductions
    * ✅ Download earning statements
    * ✅ View payment history
    * ✅ Request payout

    **Cannot:**

    * ❌ Modify fare amounts
    * ❌ Change commission rates
    * ❌ Access other drivers' earnings
  </Tab>

  <Tab title="Profile & Documents">
    **Can:**

    * ✅ Update profile information
    * ✅ Upload/update documents
    * ✅ Update vehicle information
    * ✅ Change profile photo
    * ✅ View verification status
    * ✅ Submit for re-verification

    **Cannot:**

    * ❌ Approve own documents
    * ❌ Bypass verification process
    * ❌ Change verification status
  </Tab>
</Tabs>

### Driver Dashboard Metrics

```json theme={null}
{
  "driver_stats": {
    "total_trips": 156,
    "acceptance_rate": 0.85,
    "cancellation_rate": 0.05,
    "average_rating": 4.7,
    "total_earnings": 2450000,
    "total_distance_km": 1250,
    "active_since": "2024-01-15"
  }
}
```

### Driver Categories

<CardGroup cols={2}>
  <Card title="Motorcycle Drivers" icon="motorcycle">
    **Vehicles:** 🏍️ Moto, 🏍️ Moto Carga

    **Services:**

    * Quick rides (1-2 passengers)
    * Small package delivery
    * Express courier

    **Advantages:**

    * High maneuverability
    * Lower fuel costs
    * Faster in traffic
  </Card>

  <Card title="Car Drivers" icon="car">
    **Vehicles:** 🚗 Carro, 🚙 Carro Carga

    **Services:**

    * Standard rides (1-4 passengers)
    * Large package delivery
    * Family transport

    **Advantages:**

    * More comfortable
    * Weather protection
    * Higher capacity
  </Card>
</CardGroup>

***

## Administrators

### Role Description

Administrators manage the entire platform, verify drivers, handle disputes, and configure system settings.

### Access Levels

<Tabs>
  <Tab title="Super Admin">
    **Full System Access:**

    * ✅ All user management operations
    * ✅ All driver operations
    * ✅ System configuration
    * ✅ Financial reports
    * ✅ Create/delete admin accounts
    * ✅ Access audit logs
    * ✅ Database backups
    * ✅ Emergency system shutdown
  </Tab>

  <Tab title="Operations Admin">
    **Day-to-day Operations:**

    * ✅ Verify driver documents
    * ✅ Handle user support tickets
    * ✅ Monitor active trips
    * ✅ Resolve disputes
    * ✅ View reports

    **Cannot:**

    * ❌ Change system settings
    * ❌ Create admin accounts
    * ❌ Access financial data
    * ❌ Modify pricing rules
  </Tab>

  <Tab title="Support Admin">
    **Customer Support:**

    * ✅ View user profiles
    * ✅ View trip details
    * ✅ Respond to support tickets
    * ✅ Issue refunds (limited)

    **Cannot:**

    * ❌ Approve/reject drivers
    * ❌ Access financial reports
    * ❌ Change system config
    * ❌ Delete user accounts
  </Tab>
</Tabs>

### Admin Capabilities

<AccordionGroup>
  <Accordion title="User Management">
    **Operations:**

    * View all users
    * Search/filter users
    * View user details
    * View user trip history
    * Suspend user accounts
    * Activate suspended accounts
    * Block users permanently
    * Reset user passwords
    * Export user data
    * Handle GDPR requests
  </Accordion>

  <Accordion title="Driver Verification">
    **Document Review:**

    * View pending applications
    * Review driver documents
    * Zoom/rotate document images
    * Approve applications
    * Reject with feedback
    * Request additional documents
    * Verify expiration dates
    * Check authenticity

    **Background Checks:**

    * Review driving record
    * Verify identity
    * Check criminal record (if applicable)
    * Validate insurance
  </Accordion>

  <Accordion title="Platform Monitoring">
    **Real-time Dashboard:**

    * Active users count
    * Online drivers count
    * Active trips
    * Pending trip requests
    * System health metrics
    * Error rates
    * API response times

    **Alerts:**

    * High cancellation rates
    * Driver complaints
    * System errors
    * Payment failures
  </Accordion>

  <Accordion title="Financial Management">
    **Revenue Tracking:**

    * Daily/weekly/monthly revenue
    * Commission breakdown
    * Driver payouts pending
    * Payment processing fees
    * Refunds issued

    **Reports:**

    * Financial statements
    * Tax reports
    * Driver earning summaries
    * Platform fees collected
  </Accordion>

  <Accordion title="Configuration">
    **Pricing Rules:**

    * Base fare by vehicle type
    * Per-kilometer charges
    * Per-minute charges
    * Minimum fare
    * Maximum fare
    * Surge pricing triggers
    * Commission rates

    **Service Areas:**

    * Define geographic zones
    * Set zone-specific pricing
    * Enable/disable zones
    * Driver allocation rules

    **Platform Settings:**

    * Email templates
    * Notification settings
    * App version requirements
    * Maintenance mode
  </Accordion>
</AccordionGroup>

### Admin Dashboard

```dart theme={null}
// Dashboard overview data structure
{
  "overview": {
    "total_users": 5420,
    "active_users_today": 1235,
    "total_drivers": 842,
    "online_drivers": 156,
    "trips_today": 673,
    "revenue_today": 8450000,
    "pending_approvals": 23,
    "open_support_tickets": 12
  },
  "recent_activity": [
    {"type": "new_user", "timestamp": "2024-11-01 10:30:00"},
    {"type": "trip_completed", "timestamp": "2024-11-01 10:28:15"},
    {"type": "driver_approved", "timestamp": "2024-11-01 10:25:00"}
  ],
  "alerts": [
    {"level": "warning", "message": "High cancellation rate in Zone A"},
    {"level": "info", "message": "23 drivers awaiting approval"}
  ]
}
```

***

## Companies

### Role Description

Companies are organizations that manage fleets of drivers and vehicles under their brand.

### Company Registration

<Steps>
  <Step title="Company Information">
    * Legal company name
    * Tax ID / Business registration number
    * Physical address
    * Contact email
    * Contact phone
    * Company logo
  </Step>

  <Step title="Legal Documents">
    * Business license
    * Tax registration
    * Insurance certificate
    * Operating permits
  </Step>

  <Step title="Admin Approval">
    Platform admin reviews and approves company registration
  </Step>

  <Step title="Setup">
    * Create company admin account
    * Configure commission agreement
    * Set up payment methods
    * Define service areas
  </Step>
</Steps>

### Company Permissions

<Tabs>
  <Tab title="Fleet Management">
    **Driver Management:**

    * ✅ Register drivers under company
    * ✅ Assign vehicles to drivers
    * ✅ Monitor driver performance
    * ✅ View driver locations (when online)
    * ✅ Set driver schedules
    * ✅ Deactivate drivers

    **Vehicle Management:**

    * ✅ Register company vehicles
    * ✅ Track vehicle maintenance
    * ✅ Assign vehicles to drivers
    * ✅ Monitor vehicle status
    * ✅ Schedule inspections
  </Tab>

  <Tab title="Performance">
    **Analytics:**

    * ✅ Fleet-wide statistics
    * ✅ Driver performance comparisons
    * ✅ Revenue by driver
    * ✅ Trip volume trends
    * ✅ Service area heat maps
    * ✅ Customer ratings breakdown

    **Reports:**

    * Daily operations summary
    * Weekly performance report
    * Monthly financial statement
    * Driver ranking report
    * Vehicle utilization report
  </Tab>

  <Tab title="Branding">
    **Customization:**

    * ✅ Upload company logo
    * ✅ Set brand colors
    * ✅ Customize driver uniforms
    * ✅ Vehicle branding requirements

    **Cannot:**

    * ❌ Modify core app design
    * ❌ Change platform name
    * ❌ Remove Viax branding completely
  </Tab>
</Tabs>

### Company Dashboard

```json theme={null}
{
  "company_metrics": {
    "total_drivers": 45,
    "active_drivers": 32,
    "total_vehicles": 50,
    "trips_this_month": 2150,
    "revenue_this_month": 32500000,
    "average_driver_rating": 4.6,
    "fleet_utilization": 0.71
  },
  "top_drivers": [
    {"name": "Carlos R.", "trips": 156, "rating": 4.9},
    {"name": "Maria S.", "trips": 142, "rating": 4.8}
  ]
}
```

***

## Permission Matrix

<Tabs>
  <Tab title="Users">
    | Feature          | Permission |
    | ---------------- | ---------- |
    | Request trips    | ✅          |
    | Cancel trips     | ✅          |
    | View own history | ✅          |
    | Accept trips     | ❌          |
    | View all trips   | ❌          |
    | Verify drivers   | ❌          |
    | Change pricing   | ❌          |
  </Tab>

  <Tab title="Drivers">
    | Feature                 | Permission |
    | ----------------------- | ---------- |
    | Request trips (as user) | ✅\*        |
    | Accept trip requests    | ✅          |
    | Update location         | ✅          |
    | View earnings           | ✅          |
    | Verify other drivers    | ❌          |
    | Access admin panel      | ❌          |
    | Modify pricing          | ❌          |

    \*Drivers can also request trips as users
  </Tab>

  <Tab title="Admins">
    | Feature           | Super | Operations | Support   |
    | ----------------- | ----- | ---------- | --------- |
    | Verify drivers    | ✅     | ✅          | ❌         |
    | Manage users      | ✅     | ✅          | View only |
    | Financial reports | ✅     | ❌          | ❌         |
    | System config     | ✅     | ❌          | ❌         |
    | Create admins     | ✅     | ❌          | ❌         |
    | View audit logs   | ✅     | ✅          | ❌         |
    | Support tickets   | ✅     | ✅          | ✅         |
  </Tab>

  <Tab title="Companies">
    | Feature                | Permission |
    | ---------------------- | ---------- |
    | Manage own drivers     | ✅          |
    | View own fleet data    | ✅          |
    | Assign vehicles        | ✅          |
    | View company reports   | ✅          |
    | Manage other companies | ❌          |
    | Access platform config | ❌          |
    | Verify drivers         | ❌\*        |

    \*Must submit to platform admin for approval
  </Tab>
</Tabs>

## Role Transitions

<Info>
  Users can upgrade their roles but typically cannot downgrade without admin intervention.
</Info>

**Possible Transitions:**

```mermaid theme={null}
graph LR
    A[User] -->|Register as Driver| B[User + Driver]
    B -->|Create Company| C[Company Owner]
    A -->|Admin Invite| D[Administrator]
    B -->|Admin Invite| D
```

**Important Notes:**

* A user can be both a customer and driver (separate profiles)
* Company owners are typically also drivers
* Admins have separate accounts (not linked to user/driver accounts)
* Role changes require verification/approval

<Check>
  Viax's role-based permission system ensures secure, organized access control while maintaining flexibility for different user types and business models.
</Check>