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

# Dashboard & Analytics

> Real-time metrics, KPIs, and analytics for platform monitoring

## Overview

The Admin Dashboard provides a comprehensive, real-time view of your platform's performance with interactive metrics, charts, and activity feeds.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/braian551-viax/images/admin-dashboard.png" alt="Admin Dashboard" />

## Dashboard Components

### Welcome Section

The dashboard greets administrators with a personalized welcome message that adapts based on time of day:

```dart admin/presentation/screens/admin_dashboard_tab.dart theme={null}
Widget _buildWelcomeSection(String adminName) {
  final hour = DateTime.now().hour;
  String greeting = 'Buenos días';
  IconData greetingIcon = Icons.wb_sunny_rounded;

  if (hour >= 12 && hour < 18) {
    greeting = 'Buenas tardes';
    greetingIcon = Icons.wb_cloudy_rounded;
  } else if (hour >= 18) {
    greeting = 'Buenas noches';
    greetingIcon = Icons.nightlight_round;
  }

  return AccentGlassContainer(
    accentColor: AppColors.primary,
    child: Row(
      children: [
        Container(
          decoration: BoxDecoration(
            color: AppColors.primary,
            borderRadius: BorderRadius.circular(18),
          ),
          child: Icon(greetingIcon, color: Colors.white, size: 30),
        ),
        Text(adminName, style: TextStyle(fontSize: 24, fontWeight: FontWeight.w800)),
      ],
    ),
  );
}
```

## Real-Time Metrics

The dashboard displays four key metric cards, all clickable for detailed views:

<CardGroup cols={2}>
  <Card title="Total Users" icon="users" color="#667eea">
    **Main Value:** Total registered users

    **Subtitle:** Active users count

    **Click Action:** Navigate to User Management
  </Card>

  <Card title="Trip Requests" icon="route" color="#11998e">
    **Main Value:** Total trip requests

    **Subtitle:** Requests today

    **Click Action:** Navigate to Statistics tab
  </Card>

  <Card title="Platform Earnings" icon="dollar-sign" color="#FFFF00">
    **Main Value:** Total earnings

    **Subtitle:** Today's earnings

    **Click Action:** Navigate to Statistics tab
  </Card>

  <Card title="Pending Reports" icon="exclamation-triangle" color="#ffa726">
    **Main Value:** Pending reports count

    **Subtitle:** Requires attention

    **Click Action:** Navigate to Audit Logs
  </Card>
</CardGroup>

### Metric Card Implementation

```dart admin/presentation/screens/admin_dashboard_tab.dart theme={null}
Widget _buildStatsGrid() {
  final users = _dashboardData?['usuarios'] ?? {};
  final solicitudes = _dashboardData?['solicitudes'] ?? {};
  final ingresos = _dashboardData?['ingresos'] ?? {};
  final reportes = _dashboardData?['reportes'] ?? {};

  return GridView.count(
    crossAxisCount: 2,
    crossAxisSpacing: 14,
    mainAxisSpacing: 14,
    children: [
      StatCard(
        title: 'Usuarios',
        value: (users['total_usuarios'] ?? 0).toString(),
        subtitle: 'Activos: ${users['usuarios_activos'] ?? 0}',
        icon: Icons.people_rounded,
        color: AppColors.blue600,
        onTap: () {
          Navigator.pushNamed(context, RouteNames.adminUsers,
              arguments: {'admin_id': adminId, 'admin_user': adminUser});
        },
      ),
      // Additional cards...
    ],
  );
}
```

## Dashboard Data Structure

The dashboard receives comprehensive statistics from the backend:

```json theme={null}
{
  "usuarios": {
    "total_usuarios": 1250,
    "total_clientes": 980,
    "total_conductores": 270,
    "usuarios_activos": 1100,
    "registros_hoy": 45
  },
  "solicitudes": {
    "total_solicitudes": 5840,
    "completadas": 5200,
    "canceladas": 540,
    "en_proceso": 100,
    "solicitudes_hoy": 120
  },
  "ingresos": {
    "ingresos_totales": 125000000,
    "ingresos_hoy": 2500000
  },
  "reportes": {
    "reportes_pendientes": 12
  },
  "actividades_recientes": [
    {
      "tipo": "USER_REGISTER",
      "descripcion": "Nuevo usuario registrado",
      "nombre": "Juan",
      "apellido": "Pérez",
      "fecha_creacion": "2026-03-05T10:30:00Z"
    }
  ],
  "registros_ultimos_7_dias": [
    {"fecha": "2026-02-28", "cantidad": 35},
    {"fecha": "2026-03-01", "cantidad": 42}
  ]
}
```

## Platform Earnings

A dedicated section shows platform commission earnings from transport companies:

```dart admin/presentation/screens/admin_dashboard_tab.dart theme={null}
Widget _buildPlatformEarningsCard() {
  return ActionCard(
    title: 'Ganancias Plataforma',
    subtitle: 'Ver cuentas por cobrar de empresas',
    icon: Icons.account_balance_rounded,
    color: AppColors.primary,
    onTap: () {
      Navigator.push(
        context,
        MaterialPageRoute(
          builder: (_) => PlatformEarningsScreen(adminId: adminId),
        ),
      );
    },
  );
}
```

## Recent Activity Feed

The dashboard displays the latest system activities with color-coded icons:

<Tabs>
  <Tab title="Login Events">
    **Icon:** Login rounded

    **Color:** Green (#11998e)

    **Example:** "Usuario inició sesión"
  </Tab>

  <Tab title="Registration">
    **Icon:** Person add rounded

    **Color:** Yellow (#FFFF00)

    **Example:** "Nuevo conductor registrado"
  </Tab>

  <Tab title="Errors">
    **Icon:** Error outline

    **Color:** Red (#f5576c)

    **Example:** "Error en procesamiento de pago"
  </Tab>

  <Tab title="Updates">
    **Icon:** Edit rounded

    **Color:** Orange (#ffa726)

    **Example:** "Perfil de usuario actualizado"
  </Tab>
</Tabs>

### Activity Item Implementation

```dart admin/presentation/screens/admin_dashboard_tab.dart theme={null}
Widget _buildActivityItem(Map<String, dynamic> actividad) {
  final tipo = actividad['tipo']?.toString().toUpperCase() ?? '';
  Color iconColor = AppColors.primary;
  IconData iconData = Icons.notifications_active_rounded;

  if (tipo.contains('LOGIN')) {
    iconColor = AppColors.success;
    iconData = Icons.login_rounded;
  } else if (tipo.contains('REGISTER')) {
    iconColor = AppColors.accent;
    iconData = Icons.person_add_rounded;
  } else if (tipo.contains('ERROR')) {
    iconColor = AppColors.error;
    iconData = Icons.error_outline_rounded;
  }

  return ListTile(
    leading: Container(
      decoration: BoxDecoration(
        color: iconColor.withValues(alpha: 0.12),
        borderRadius: BorderRadius.circular(14),
      ),
      child: Icon(iconData, color: iconColor),
    ),
    title: Text(actividad['descripcion'] ?? 'Sin descripción'),
    subtitle: Text('${actividad['nombre']} • ${_formatDate(actividad['fecha_creacion'])}'),
  );
}
```

## Time Formatting

Activities are displayed with human-readable relative timestamps:

```dart admin/presentation/screens/admin_dashboard_tab.dart theme={null}
String _formatDate(String? dateStr) {
  if (dateStr == null) return '';
  try {
    final date = DateTime.parse(dateStr);
    final now = DateTime.now();
    final diff = now.difference(date);

    if (diff.inMinutes < 1) return 'Ahora';
    if (diff.inMinutes < 60) return 'Hace ${diff.inMinutes}m';
    if (diff.inHours < 24) return 'Hace ${diff.inHours}h';
    if (diff.inDays < 7) return 'Hace ${diff.inDays}d';
    return '${date.day}/${date.month}/${date.year}';
  } catch (e) {
    return dateStr;
  }
}
```

## Number Formatting

Large numbers are automatically formatted for readability:

```dart admin/presentation/screens/admin_dashboard_tab.dart theme={null}
String _formatNumber(dynamic value) {
  if (value == null) return '0';
  final num = double.tryParse(value.toString()) ?? 0;
  if (num >= 1000000) {
    return '${(num / 1000000).toStringAsFixed(1)}M';
  } else if (num >= 1000) {
    return '${(num / 1000).toStringAsFixed(1)}K';
  }
  return num.toStringAsFixed(0);
}
```

**Examples:**

* 1,250 → "1.3K"
* 125,000 → "125.0K"
* 2,500,000 → "2.5M"

## Loading States

The dashboard implements shimmer loading for a smooth user experience:

```dart theme={null}
if (_isLoading) {
  return const DashboardShimmer();
}
```

<Note>
  All dashboard data automatically refreshes when you pull down on the screen or navigate back to the Dashboard tab.
</Note>

## Refresh Functionality

<Steps>
  <Step title="Pull to Refresh">
    Swipe down on the dashboard to manually refresh all metrics
  </Step>

  <Step title="Auto Refresh">
    Dashboard data refreshes when navigating back from other sections
  </Step>

  <Step title="Loading State">
    Shimmer animation displays during data fetch
  </Step>
</Steps>

## Navigation Actions

Dashboard cards provide quick navigation:

| Card         | Destination            | Data Passed              |
| ------------ | ---------------------- | ------------------------ |
| **Users**    | User Management Screen | `admin_id`, `admin_user` |
| **Requests** | Statistics Tab         | Index `2`                |
| **Earnings** | Statistics Tab         | Index `2`                |
| **Reports**  | Audit Logs Screen      | `admin_id`               |

## Best Practices

<Accordion title="Monitor Daily">
  Check the dashboard daily to stay informed about platform activity, user growth, and pending tasks.
</Accordion>

<Accordion title="Review Activity Feed">
  Regularly review recent activities to catch unusual patterns or errors early.
</Accordion>

<Accordion title="Track KPIs">
  Monitor key metrics like active users, completed trips, and earnings trends.
</Accordion>

<Accordion title="Quick Actions">
  Use clickable metric cards for quick navigation to relevant management sections.
</Accordion>

## Related Features

<CardGroup cols={3}>
  <Card title="Statistics" icon="chart-bar" href="/admin/reports">
    Detailed analytics and charts
  </Card>

  <Card title="User Management" icon="users" href="/admin/user-management">
    Manage platform users
  </Card>

  <Card title="Audit Logs" icon="list" href="/admin/audit-logs">
    View all system activities
  </Card>
</CardGroup>