Skip to main content

​
Quick Start Guide

This guide will help you quickly get started with VIP2CARS, walking you through user registration, dashboard access, and creating your first client and vehicle records.
This guide assumes you’ve already completed the Installation Guide and have the application running at http://127.0.0.1:8000.

​
Prerequisites

Before starting, ensure:
  • Both development servers are running:
    • PHP server: php artisan serve
    • Vite dev server: npm run dev
  • Your browser is pointed to: http://127.0.0.1:8000
  • Database migrations have been executed successfully

​
Getting Started

1
Register a New Account
2
VIP2CARS uses authentication to protect client and vehicle data. You’ll need to create an account first.
3
  • Navigate to http://127.0.0.1:8000/register
  • Fill in the registration form:
    • Name: Your full name
    • Email: A valid email address
    • Password: At least 8 characters
    • Confirm Password: Match the password above
  • Click the Register button
    • 4
    If you ran the migrations with seeders (php artisan migrate --seed), sample client and vehicle data will already be available after you log in.
    5
    After successful registration, you’ll be automatically logged in and redirected to the dashboard.
    6
    Access the Dashboard
    7
    The dashboard is your central hub for managing clients and vehicles.
    8
    Dashboard URL: http://127.0.0.1:8000/dashboard
    9
    From the dashboard, you can:
    10
  • View system overview
  • Navigate to client management
  • Navigate to vehicle management
  • Access documentation
  • Manage your account settings
    • 11
    The sidebar menu provides quick navigation to all major sections:
    • Dashboard - Overview page
    • Clientes - Client management
    • Vehículos - Vehicle management
    • Documentation - Technical documentation
    13
    VIP2CARS uses a modern sidebar layout with the following components:
    14
    Sidebar Navigation:
    15
  • Logo and application name at the top
  • Main navigation links (Dashboard, Clientes, Vehículos)
  • Documentation link
  • User menu at the bottom (Settings, Logout)
    • 16
    Main Content Area:
    17
  • Page title and breadcrumbs
  • Action buttons (Create, Edit, Delete)
  • Data tables with search and pagination
  • Forms for data entry
    • 18
    User Menu:
    19
  • Profile settings
  • Password management
  • Two-factor authentication
  • Theme preferences (Dark/Light mode)
  • Logout
    • 20
    Create Your First Client
    21
    Let’s add a new client to the system.
    22
  • Click Clientes in the sidebar navigation
  • Click the Crear Cliente (Create Client) button
  • Fill in the client form:
    • 23
    Nombres: Juan Carlos
Apellidos: García Rodríguez
Nro. Documento: 12345678
Correo: juan.garcia@example.com
Teléfono: +51 987 654 321
    24
  • Click Guardar (Save) to create the client
    • 25
    Unique Constraints:
    • Nro. Documento (Document Number) must be unique across all clients
    • Correo (Email) must be unique across all clients
    Attempting to create a client with duplicate values will result in a validation error.
    26
    Field Validation Rules:
    27
    FieldTypeRulesMax LengthNombresStringRequired255ApellidosStringRequired255Nro. DocumentoStringRequired, Unique-CorreoEmailRequired, Unique, Valid Email-TeléfonoStringRequired20
    28
    After saving, you’ll be redirected to the clients list where your new client appears.
    29
    View Client Details
    30
    From the clients list:
    31
  • Locate your newly created client
  • Click the Ver (View) or Editar (Edit) button
  • View or modify client information
  • See associated vehicles (if any)
    • 32
    Create a Vehicle Record
    33
    Now let’s add a vehicle for your client.
    34
  • Click Vehículos in the sidebar
  • Click Crear Vehículo (Create Vehicle)
  • Fill in the vehicle form:
    • 35
    Placa: ABC-123
Marca: Toyota
Modelo: Corolla
Año de Fabricación: 2022
Cliente: Juan Carlos García Rodríguez
    36
  • Select the client from the dropdown
  • Click Guardar (Save)
    • 37
    Client Selection: The client dropdown shows all registered clients in the system. You must associate each vehicle with an existing client.
    38
    Vehicle Field Validation:
    39
    FieldTypeRulesPlacaStringRequired, UniqueMarcaStringRequiredModeloStringRequiredAño de FabricaciónIntegerRequired, Valid YearClienteForeign KeyRequired, Must Exist
    40
    The Placa (license plate) must be unique. No two vehicles can have the same license plate number.
    41
    View Vehicle and Client Relationship
    42
    VIP2CARS maintains relationships between clients and vehicles:
    43
    From Vehicle View:
    44
  • Each vehicle shows its associated client
  • Click the client name to view client details
    • 45
    From Client View:
    46
  • Client detail pages show all associated vehicles
  • View the complete history of vehicles owned by a client
    • 47
    Database Relationship:
    48
    public function vehiculos()
{
    return $this->hasMany(Vehiculo::class, 'id_cliente', 'id_cliente');
}
    49
    public function cliente()
{
    return $this->belongsTo(Cliente::class, 'id_cliente', 'id_cliente');
}
    50
    Edit Records
    51
    To modify existing records:
    52
    Edit a Client:
    53
  • Go to Clientes list
  • Click Editar (Edit) on the client row
  • Modify the fields
  • Click Actualizar (Update)
    • 54
    Edit a Vehicle:
    55
  • Go to Vehículos list
  • Click Editar (Edit) on the vehicle row
  • Modify the fields
  • Click Actualizar (Update)
    • 56
    When editing, unique constraint validation is adjusted to allow the current record’s values while preventing duplicates with other records.
    57
    Delete Records
    58
    To remove records from the system:
    59
    Delete a Vehicle:
    60
  • Navigate to the vehicles list
  • Click Eliminar (Delete) on the vehicle row
  • Confirm the deletion
  • The vehicle is permanently removed
    • 61
    Delete a Client:
    62
  • Navigate to the clients list
  • Click Eliminar (Delete) on the client row
  • Confirm the deletion
    • 63
    Cascade Delete: When you delete a client, ALL associated vehicles are automatically deleted. This action cannot be undone.Database Foreign Key:
    FOREIGN KEY (id_cliente) 
REFERENCES clientes(id_cliente) 
ON DELETE CASCADE

    ​
    Common Workflows

    ​
    Workflow 1: Register New Customer with Vehicle

    1. Create Client Record
      • Navigate to Clientes → Crear Cliente
      • Enter customer details
      • Save the client
    2. Create Vehicle Record
      • Navigate to Vehículos → Crear Vehículo
      • Enter vehicle details
      • Select the newly created client
      • Save the vehicle
    3. Verify Relationship
      • View the client record
      • Confirm the vehicle appears in the client’s vehicle list

    ​
    Workflow 2: Update Client Information

    1. Locate Client
      • Go to Clientes list
      • Search for the client by name or document number
    2. Edit Details
      • Click Editar
      • Update the necessary fields
      • Click Actualizar
    3. Verify Changes
      • Return to client list
      • Confirm updated information is displayed

    ​
    Workflow 3: Transfer Vehicle to Another Client

    1. Edit Vehicle
      • Navigate to Vehículos
      • Click Editar on the vehicle to transfer
    2. Change Client Association
      • Select a different client from the dropdown
      • Save the changes
    3. Verify Transfer
      • Check the old client’s record (vehicle should be gone)
      • Check the new client’s record (vehicle should appear)

    ​
    Authentication Features

    ​
    Login and Logout

    Login: Logout:
    • Click your name in the sidebar
    • Select Logout
    • You’ll be redirected to the homepage

    ​
    Password Reset

    If you forget your password:
    1. Go to the login page
    2. Click Forgot Password?
    3. Enter your email address
    4. Check your email for reset instructions
    5. Follow the link to set a new password
    Password reset requires proper mail configuration in your .env file. For development, check storage/logs/laravel.log if MAIL_MAILER=log.

    ​
    Account Settings

    Access account settings from the user menu: Profile Settings:
    • Update your name and email
    • View account information
    Password Management:
    • Change your password
    • Requires current password for verification
    Two-Factor Authentication:
    • Enable 2FA for enhanced security
    • Scan QR code with authenticator app
    • Save recovery codes
    Appearance:
    • Toggle between light and dark modes
    • Preferences are saved per user

    ​
    Tips for Efficient Use

    Keyboard Navigation:
    • Use Tab to navigate between form fields
    • Press Enter to submit forms
    • Use browser back button or breadcrumbs to navigate
    Search and Filter: While not explicitly shown in controllers, you can use browser’s find function (Ctrl+F / Cmd+F) to search within tables on the page.
    Data Validation: The system validates all input before saving. If you see an error message, check:
    • Required fields are filled
    • Email format is valid
    • Document number and email are unique
    • Numeric fields contain valid numbers

    ​
    API Routes

    VIP2CARS uses Laravel resource routes for RESTful operations:

    ​
    Client Routes

    MethodURIActionRoute Name
    GET/clientesList all clientsclientes.index
    GET/clientes/createShow create formclientes.create
    POST/clientesStore new clientclientes.store
    GET/clientes/Show clientclientes.show
    GET/clientes//editShow edit formclientes.edit
    PUT/PATCH/clientes/Update clientclientes.update
    DELETE/clientes/Delete clientclientes.destroy

    ​
    Vehicle Routes

    MethodURIActionRoute Name
    GET/vehiculosList all vehiclesvehiculos.index
    GET/vehiculos/createShow create formvehiculos.create
    POST/vehiculosStore new vehiclevehiculos.store
    GET/vehiculos/Show vehiclevehiculos.show
    GET/vehiculos//editShow edit formvehiculos.edit
    PUT/PATCH/vehiculos/Update vehiclevehiculos.update
    DELETE/vehiculos/Delete vehiclevehiculos.destroy
    All client and vehicle routes are protected by the auth and verified middleware, requiring authenticated users.

    ​
    Understanding the Tech Stack

    ​
    Livewire Components

    VIP2CARS uses Livewire for reactive components without writing JavaScript:
    • Real-time Validation: Form fields validate as you type
    • Dynamic Updates: Pages update without full page refresh
    • Component Communication: Seamless data flow between components

    ​
    Flux UI Components

    The interface uses Flux UI components for consistent design:
    • Buttons: Primary, secondary, danger actions
    • Forms: Input fields, selects, textareas
    • Tables: Data display with sorting and actions
    • Modals: Confirmation dialogs and forms
    • Navigation: Sidebar, breadcrumbs, menus

    ​
    Tailwind CSS

    Styling is powered by Tailwind CSS v4:
    • Utility-First: Rapid UI development
    • Responsive Design: Mobile-first approach
    • Dark Mode: Built-in theme switching
    • Custom Components: Reusable design patterns

    ​
    Troubleshooting Common Issues

    ​
    Issue: Can’t Access Dashboard

    Symptom: Redirected to login when accessing /dashboard Solution: You must be logged in. Register a new account or log in with existing credentials.

    ​
    Issue: Validation Errors on Form Submit

    Symptom: Form shows error messages Solution: Check that:
    • All required fields are filled
    • Email format is correct (user@example.com)
    • Document number and email are not already used by another client
    • Year is a valid 4-digit number

    ​
    Issue: Client Dropdown Empty in Vehicle Form

    Symptom: No clients appear in vehicle creation form Solution: Create at least one client first. Vehicles must be associated with existing clients.

    ​
    Issue: Changes Not Appearing

    Symptom: Updates don’t show immediately Solution:
    1. Refresh the page (F5)
    2. Clear browser cache
    3. Check that Vite dev server is running
    npm run dev

    ​
    Next Steps

    Now that you’re familiar with the basics:
    1. Explore Advanced Features:
      • Set up two-factor authentication
      • Customize your profile
      • Export technical documentation
    2. Learn More About Laravel:
    3. Customize VIP2CARS:
      • Add custom fields to models
      • Create additional reports
      • Implement search functionality
      • Add PDF export features
    Access the built-in technical documentation by clicking Documentation in the sidebar menu for detailed information about the system architecture.

    ​
    Getting Help

    If you encounter issues:
    1. Check Laravel logs: storage/logs/laravel.log
    2. Review validation error messages
    3. Ensure all services are running
    4. Verify database connection
    For development questions, consult the Laravel Documentation which covers all framework features used in VIP2CARS.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us