Clients Module

Overview

The Clients module is the central hub for managing customer relationships. It provides client segmentation, purchase tracking, and integration with sales, invoices, and messages.

Client Segmentation

Categorize clients as Premium, Regular, or Occasional based on behavior

Purchase History

Track total purchases and transaction history per client

Multi-Channel Relations

Integrated with sales, invoices, and messaging systems

Status Management

Active/Inactive status tracking for client engagement

Cliente Model

The Cliente model is the foundation of customer data management:

app/Models/Cliente.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Cliente extends Model
{
    use HasFactory;

    protected $fillable = [
        'nombre',
        'apellido',
        'email',
        'telefono',
        'estado',
        'segmento',
        'total_compras',
    ];

    public function ventas()
    {
        return $this->hasMany(Venta::class);
    }

    public function facturas()
    {
        return $this->hasMany(Factura::class);
    }

    public function mensajes()
    {
        return $this->hasMany(Mensaje::class);
    }
}

Model Relationships

Ventas (Sales)
Facturas (Invoices)
Mensajes (Messages)

Each client can have multiple sales (hasMany):

public function ventas()
{
    return $this->hasMany(Venta::class);
}

Usage Example:

$cliente = Cliente::find(1);
$ventas = $cliente->ventas;

// Get total sales amount
$total = $cliente->ventas()->sum('total');

Each client can have multiple invoices (hasMany):

public function facturas()
{
    return $this->hasMany(Factura::class);
}

Usage Example:

$cliente = Cliente::find(1);
$facturas = $cliente->facturas;

// Get pending invoices
$pendientes = $cliente->facturas()->where('estado', 'pendiente')->get();

Each client can have multiple messages (hasMany):

public function mensajes()
{
    return $this->hasMany(Mensaje::class);
}

Usage Example:

$cliente = Cliente::find(1);
$mensajes = $cliente->mensajes;

// Get unread messages
$no_leidos = $cliente->mensajes()->where('leido', false)->count();

Database Schema

The clientes table structure from the migration:

database/migrations/2026_03_03_191644_create_clientes_table.php

Schema::create('clientes', function (Blueprint $table) {
    $table->id();
    $table->string('nombre');
    $table->string('apellido');
    $table->string('email')->unique();
    $table->string('telefono')->nullable();
    $table->enum('estado', ['activo', 'inactivo'])->default('activo');
    $table->enum('segmento', ['premium', 'regular', 'ocasional'])->default('regular');
    $table->integer('total_compras')->default(0);
    $table->timestamps();
});

Table Fields

Field	Type	Constraints	Description
`id`	bigint	Primary key	Unique client identifier
`nombre`	string	Required	Client first name
`apellido`	string	Required	Client last name
`email`	string	Unique, Required	Client email address
`telefono`	string	Nullable	Contact phone number
`estado`	enum	Default: ‘activo’	Client status
`segmento`	enum	Default: ‘regular’	Client segment category
`total_compras`	integer	Default: 0	Total purchase count
`timestamps`	timestamps	Auto	created_at, updated_at

Client Segmentation

Client segmentation helps prioritize service and personalize marketing strategies based on customer value.

Premium
Regular
Occasional

Premium ClientsHigh-value customers with frequent purchases and large transaction volumes.

Cliente::where('segmento', 'premium')->get();

Characteristics:

21+ total purchases
High average order value
Priority support access

Regular ClientsStandard customers with moderate purchase frequency. This is the default segment.

Cliente::where('segmento', 'regular')->get();

Characteristics:

5-20 total purchases
Standard support level
Most common segment

Occasional ClientsInfrequent buyers or new customers with limited purchase history.

Cliente::where('segmento', 'ocasional')->get();

Characteristics:

0-4 total purchases
Potential for conversion
Targeted campaigns

Client Status

Clients can be marked as active or inactive:

Activo

Active clients currently engaging with the platform

Cliente::where('estado', 'activo')->count();
// Returns: 2,340 (82% of total)

Inactivo

Inactive clients who haven’t engaged recently

Cliente::where('estado', 'inactivo')->count();
// Returns: 507 (18% of total)

Client View Features

The client interface (clientes.blade.php) provides:

Dashboard Metrics

Total Clients: 2,847 (+15% this month)
Active Clients: 2,340 (82% of total)
New Clients: 124 this month
Inactive Clients: 507 (18% of total)

Analytics Charts

New Clients by Month

Bar chart showing monthly client acquisition trends

Client Segmentation

Doughnut chart displaying segment distribution:

Premium: 15%
Regular: 45%
Occasional: 22%
Inactive: 18%

Client Management Table

The main client table displays:

Client ID
Full name with icon
Email address
Phone number
Total purchases count
Status badge (Active/Inactive)
Action buttons (View, Edit, Delete)

The interface includes real-time search and status filtering for efficient client lookup.

Usage Examples

Creating a New Client

use App\Models\Cliente;

$cliente = Cliente::create([
    'nombre' => 'Juan',
    'apellido' => 'Pérez',
    'email' => '[email protected]',
    'telefono' => '+57 300 123 4567',
    'estado' => 'activo',
    'segmento' => 'regular',
    'total_compras' => 0
]);

// Get all clients with their sales and invoices
$clientes = Cliente::with(['ventas', 'facturas', 'mensajes'])->get();

foreach ($clientes as $cliente) {
    $total_sales = $cliente->ventas->count();
    $pending_invoices = $cliente->facturas()->where('estado', 'pendiente')->count();
    $unread_messages = $cliente->mensajes()->where('leido', false)->count();
}

Updating Client Segment

$cliente = Cliente::find(1);

// Upgrade to premium based on purchases
if ($cliente->total_compras >= 21) {
    $cliente->segmento = 'premium';
    $cliente->save();
}

Finding Premium Active Clients

$premium_activos = Cliente::where('segmento', 'premium')
    ->where('estado', 'activo')
    ->orderBy('total_compras', 'desc')
    ->get();

Client Statistics

// Total clients by segment
$premium = Cliente::where('segmento', 'premium')->count();
$regular = Cliente::where('segmento', 'regular')->count();
$ocasional = Cliente::where('segmento', 'ocasional')->count();

// Average purchases per client
$avg_compras = Cliente::avg('total_compras');

// Clients with unread messages
$con_mensajes = Cliente::whereHas('mensajes', function($query) {
    $query->where('leido', false);
})->count();

Key Features

Unique Email

Email addresses must be unique across all clients

Full Name Tracking

Separate first and last name fields for better organization

Optional Phone

Telephone field is nullable for flexibility

Purchase Counter

Automatic tracking of total purchases per client

Three-Tier Segmentation

Premium, Regular, and Occasional categories

Status Toggle

Active/Inactive status for engagement tracking

Cascade Relations

Deleting a client removes all related sales, invoices, and messages

Default Values

New clients default to ‘activo’ status and ‘regular’ segment

Timestamp Tracking

Automatic created_at and updated_at timestamps

Get Started

Core Features

Business Modules

Configuration

Overview

Client Segmentation

Purchase History

Multi-Channel Relations

Status Management

Cliente Model

Model Relationships

Database Schema

Table Fields

Client Segmentation

Client Status

Activo

Inactivo

Client View Features

Dashboard Metrics

Analytics Charts

New Clients by Month

Client Segmentation

Client Management Table

Usage Examples

Creating a New Client

Updating Client Segment

Finding Premium Active Clients

Client Statistics

Key Features

Unique Email

Full Name Tracking

Optional Phone

Purchase Counter

Three-Tier Segmentation

Status Toggle

Cascade Relations

Default Values

Timestamp Tracking

Build docs developers (and LLMs) love

Get Started

Core Features

Business Modules

Configuration

​Overview

Client Segmentation

Purchase History

Multi-Channel Relations

Status Management

​Cliente Model

​Model Relationships

​Database Schema

​Table Fields

​Client Segmentation

​Client Status

Activo

Inactivo

​Client View Features

​Dashboard Metrics

​Analytics Charts

New Clients by Month

Client Segmentation

​Client Management Table

​Usage Examples

​Creating a New Client

​Querying Clients with Related Data

​Updating Client Segment

​Finding Premium Active Clients

​Client Statistics

​Key Features

Unique Email

Full Name Tracking

Optional Phone

Purchase Counter

Three-Tier Segmentation

Status Toggle

Cascade Relations

Default Values

Timestamp Tracking

Build docs developers (and LLMs) love

Overview

Cliente Model

Model Relationships

Database Schema

Table Fields

Client Segmentation

Client Status

Client View Features

Dashboard Metrics

Analytics Charts

Client Management Table

Usage Examples

Creating a New Client

Querying Clients with Related Data

Updating Client Segment

Finding Premium Active Clients

Client Statistics

Key Features