Quick Start Guide

This guide will help you get GIMA up and running quickly and take you through the essential steps to start managing your assets.

Prerequisites

Before you begin, ensure you have:

PHP 8.2 or higher installed
Composer dependency manager
PostgreSQL 12 or higher
Node.js and npm (for frontend assets)
Git (to clone the repository)

For detailed installation instructions, see the Installation Guide.

Installation Steps

Clone the Repository

Clone the GIMA repository to your local machine:

git clone <repository-url> gima
cd gima

Install Dependencies

Install PHP and JavaScript dependencies:

composer install

Configure Environment

Copy the example environment file and generate an application key:

cp .env.example .env
php artisan key:generate

Edit .env and configure your database connection:

.env

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=gima_bd
DB_USERNAME=postgres
DB_PASSWORD=your_password_here

Create the gima_bd database in PostgreSQL before running migrations.

Run Database Migrations

Create the database tables:

php artisan migrate

This creates all necessary tables including users, assets, maintenance schedules, and more.

Seed Initial Data

Populate the database with roles, permissions, and test users:

php artisan db:seed --class=RolesSeeder

This creates four test users with different roles:

Role	Email	Password
Admin	[email protected]	12345678
Supervisor	[email protected]	12345678
Technician	[email protected]	12345678
Reporter	[email protected]	12345678

Change these passwords in production! These are for development only.

Start the Development Server

Launch the Laravel development server:

php artisan serve

The API will be available at http://localhost:8000

Your First Workflow

Let’s walk through a complete maintenance workflow from login to dashboard view.

1. Authenticate as Supervisor

First, log in to get an access token:

curl -X POST http://localhost:8000/api/autenticacion/iniciar-sesion \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "12345678"
  }'

Response:

{
  "estado": "exito",
  "mensaje": "Login correcto",
  "data": {
    "usuario": "Roberto Supervisor",
    "roles": ["supervisor"],
    "token": "1|abc123...xyz789"
  }
}

Save the token - you’ll need it for all subsequent API requests. Include it in the Authorization header as Bearer {token}.

2. View Your Profile

Verify your authentication and see your assigned roles:

curl -X GET http://localhost:8000/api/autenticacion/perfil \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response:

{
  "estado": "exito",
  "data": {
    "id": 2,
    "name": "Roberto Supervisor",
    "email": "[email protected]",
    "telefono": null,
    "estado": "activo"
  },
  "roles_asignados": ["supervisor"]
}

3. Access the Supervisor Dashboard

As a supervisor, you have access to the supervision area:

curl -X GET http://localhost:8000/api/supervision/auditoria \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response:

{
  "mensaje": "Auditoría de calidad (Solo Supervisor)"
}

Try accessing endpoints with different user roles to see how permissions work. For example, a technician cannot access /api/supervision/* routes.

4. Understanding Role-Based Access

GIMA uses role-based access control. Here’s what each role can access:

Admin Routes
Supervisor Routes
Technician Routes
Reporter Routes

# Full system access
GET  /api/admin/dashboard
# Plus all routes available to other roles

Admins have access to everything including user management and master data configuration.

# Supervision area
GET  /api/supervision/auditoria

# Technical area (shared with technicians)
GET  /api/tecnica/ordenes-trabajo

# Authentication
GET  /api/autenticacion/perfil

Supervisors can manage assets, schedule maintenance, and assign work orders.

# Technical area
GET  /api/tecnica/ordenes-trabajo

# Authentication
GET  /api/autenticacion/perfil

Technicians can view and complete assigned maintenance tasks.

# Reports area
GET  /api/reportes/mensuales

# Authentication
GET  /api/autenticacion/perfil

Reporters can submit failure reports and view basic asset information.

Database Structure Overview

Understanding the core tables will help you work with GIMA effectively:

Core Entities

users - System Users

Stores user accounts with authentication details and role assignments.Key fields:

name, email, password - Authentication credentials
telefono - Contact phone number
estado - User status (active/inactive)
aprobado_por - Admin who approved the user
Roles assigned via Spatie Permission package

activos - Physical Assets

Central table for all organizational assets.Key fields:

articulo_id - Links to asset type/category
ubicacion_id - Current asset location
estado - Asset state (operativo, en_mantenimiento, fuera_de_servicio)
valor - Asset value for cost tracking

mantenimientos - Maintenance Work Orders

Tracks all maintenance activities on assets.Key fields:

activo_id - Asset being maintained
supervisor_id - Supervising user
tecnico_principal_id - Assigned technician
tipo - Type (preventivo, correctivo)
reporte_id - Optional linked failure report
fecha_apertura, fecha_cierre - Maintenance timeframe
estado - Status (pendiente, en_proceso, completado)
costo_total - Total maintenance cost

calendario_mantenimientos - Maintenance Schedule

Schedules future maintenance activities.Key fields:

activo_id - Asset to be maintained
tipo - Maintenance type (usually preventivo)
fecha_programada - Scheduled date/time
tecnico_asignado - Assigned technician
estado - Status (pendiente, completado, cancelado)

repuestos - Spare Parts Inventory

Tracks available spare parts and materials.Usage tracked via:

repuestos_usados - Junction table linking maintenance to consumed parts
sesiones_mantenimiento - Individual work sessions with time and resource tracking

Next Steps

Detailed Installation

Production-ready setup with security best practices

API Reference

Complete API endpoint documentation

Asset Management

Learn how to register and manage assets

Scheduling Maintenance

Schedule preventive and corrective maintenance

Development Tips

Quick Development Server: Use the composer script to start all services at once:

composer dev

This runs the Laravel server, queue worker, logs, and Vite concurrently.

Authentication Required: All API endpoints except /api/autenticacion/iniciar-sesion and /api/autenticacion/registrar require authentication. Always include the Authorization: Bearer {token} header.

Common Issues

Database Connection Failed

Ensure PostgreSQL is running and the database gima_bd exists:

CREATE DATABASE gima_bd;

Verify your .env credentials match your PostgreSQL setup.

403 Forbidden on Protected Routes

This means your user doesn’t have the required role. Check:

Your token is valid and included in the Authorization header
Your user has the correct role assigned
The route middleware matches your role

Example: /api/admin/* routes require the admin role.

Token Not Working

Tokens are stored in the personal_access_tokens table. If you’re having issues:

Ensure Laravel Sanctum is properly installed
Check your token hasn’t expired
Verify the Authorization header format: Bearer {token} (note the space)

Testing Your Setup

Run the test suite to verify everything is working:

composer test

This runs PHPUnit tests to validate core functionality.

You’re now ready to start building with GIMA! For production deployment, see the Installation Guide for security hardening and optimization tips.

Get Started

Core Concepts

Guides

Quick Start

Quick Start Guide

Prerequisites

Installation Steps

Your First Workflow

1. Authenticate as Supervisor

2. View Your Profile

3. Access the Supervisor Dashboard

4. Understanding Role-Based Access

Database Structure Overview

Core Entities

Next Steps

Detailed Installation

API Reference

Asset Management

Scheduling Maintenance

Development Tips

Common Issues

Testing Your Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Quick Start Guide

​Prerequisites

​Installation Steps

​Your First Workflow

​1. Authenticate as Supervisor

​2. View Your Profile

​3. Access the Supervisor Dashboard

​4. Understanding Role-Based Access

​Database Structure Overview

​Core Entities

​Next Steps

Detailed Installation

API Reference

Asset Management

Scheduling Maintenance

​Development Tips

​Common Issues

​Testing Your Setup

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Installation Steps

Your First Workflow

1. Authenticate as Supervisor

2. View Your Profile

3. Access the Supervisor Dashboard

4. Understanding Role-Based Access

Database Structure Overview

Core Entities

Next Steps

Development Tips

Common Issues

Testing Your Setup