Descripción General del Dashboard Frontend

Versión: 1.0 Fecha: 2025-11-19 Proyecto: Algesta Dashboard React

Tabla de Contenidos

Resumen Ejecutivo
Descripción General de Arquitectura
Catálogo de Módulos de Funcionalidad
Stack Tecnológico
Principios de Arquitectura
Referencias Cruzadas
Inicio Rápido

Resumen Ejecutivo

El Dashboard React de Algesta es una aplicación web integral que proporciona una interfaz completa para gestionar órdenes, subastas, proveedores, activos, clientes y operaciones comerciales. El dashboard sirve a múltiples roles de usuario (Admin, Agente, Proveedor, Cliente) con experiencias y capacidades adaptadas para cada rol.

Estadísticas Clave:

11 módulos de funcionalidad que cubren el dominio completo del negocio
Más de 50 componentes UI reutilizables basados en shadcn/ui
Más de 40 rutas con control de acceso basado en roles
4 roles de usuario con capacidades distintas
Stack tecnológico moderno (React 19, TypeScript 5.8, Vite 6, Tailwind CSS 4)

Propósito: El dashboard proporciona una interfaz unificada para que todos los interesados de la plataforma gestionen el ciclo de vida completo de órdenes de mantenimiento y reparación, desde la creación hasta la subasta, asignación de proveedor, ejecución del trabajo y finalización.

Descripción General de Arquitectura

Patrón Bulletproof React

La aplicación sigue el patrón de arquitectura Bulletproof React, que enfatiza:

Organización basada en funcionalidades
Clara separación de responsabilidades
Escalabilidad y mantenibilidad
Seguridad de tipos con TypeScript
Testeabilidad

Estructura de Directorios

src/
├── features/              # Módulos de funcionalidades (11 módulos)
│   ├── auth/             # Autenticación
│   ├── orders/           # Gestión de órdenes
│   ├── marketplace/      # Subastas y marketplace
│   ├── providers/        # Funcionalidad de proveedores
│   ├── assets/           # Gestión de activos
│   ├── clients/          # Funcionalidad de clientes
│   ├── users/            # Gestión de usuarios
│   ├── dashboard/        # KPIs y métricas
│   ├── contracts-policies/ # Gestión de contratos
│   ├── accountants/      # Contabilidad
│   └── monitoring-panel/ # Monitoreo de mensajes
├── components/ui/        # Componentes UI compartidos (50+ componentes)
│   ├── button.tsx
│   ├── form.tsx
│   ├── data-table-server.tsx
│   └── ...
├── lib/                  # Utilidades principales
│   ├── auth.tsx          # Configuración de autenticación
│   ├── api-client.ts     # Cliente HTTP Axios
│   ├── react-query.ts    # Configuración de React Query
│   ├── authorization.tsx # Lógica RBAC
│   └── storage.ts        # Abstracción de localStorage
├── app/                  # Configuración de la aplicación
│   ├── router.tsx        # Definiciones de rutas
│   └── provider.tsx      # Proveedores de la app
├── store/                # Stores de Zustand
│   ├── use-user-store.ts
│   ├── use-quotation-store.ts
│   └── ...
├── config/               # Configuración
│   ├── env.ts            # Variables de entorno
│   ├── paths.ts          # Definiciones de rutas
│   └── constants.ts      # Constantes de la app
├── types/                # Definiciones de tipos TypeScript
│   ├── api.ts            # Tipos de API
│   └── authorization.ts  # Tipos de autenticación
└── utils/                # Funciones utilitarias
    ├── sidebar-settings.ts
    └── ...

Arquitectura del Sistema

graph TB
    Admin["Admin<br/>[Persona]<br/>Administrador de plataforma"]
    Agent["Agente<br/>[Persona]<br/>Agente de servicio al cliente"]
    Provider["Proveedor<br/>[Persona]<br/>Proveedor de servicios"]
    Client["Cliente<br/>[Persona]<br/>Cliente final"]

    Dashboard["Dashboard React<br/>[React 19, TypeScript]<br/>Aplicación web que proporciona UI para todos los roles"]
    Gateway["API Gateway<br/>[NestJS]<br/>Punto de entrada único para todas las solicitudes de API"]

    subgraph Backend["Microservicios Backend"]
        OrdersMS["Orders MS<br/>[NestJS]<br/>Gestión de órdenes"]
        ProviderMS["Provider MS<br/>[NestJS]<br/>Gestión de proveedores y subastas"]
        AuthMS["Auth MS<br/>[NestJS]<br/>Autenticación"]
        NotificationsMS["Notifications MS<br/>[NestJS]<br/>Notificaciones por email"]
    end

    Admin -->|"Usa<br/>HTTPS"| Dashboard
    Agent -->|"Usa<br/>HTTPS"| Dashboard
    Provider -->|"Usa<br/>HTTPS"| Dashboard
    Client -->|"Usa<br/>HTTPS"| Dashboard

    Dashboard -->|"Realiza llamadas API<br/>HTTPS/REST"| Gateway

    Gateway -->|"Enruta solicitudes<br/>Redis/Kafka"| OrdersMS
    Gateway -->|"Enruta solicitudes<br/>Redis/Kafka"| ProviderMS
    Gateway -->|"Enruta solicitudes<br/>Redis/Kafka"| AuthMS
    Gateway -->|"Enruta solicitudes<br/>Redis/Kafka"| NotificationsMS

    style Admin fill:#08427b,stroke:#052e56,color:#ffffff
    style Agent fill:#08427b,stroke:#052e56,color:#ffffff
    style Provider fill:#08427b,stroke:#052e56,color:#ffffff
    style Client fill:#08427b,stroke:#052e56,color:#ffffff
    style Dashboard fill:#438dd5,stroke:#2e6295,color:#ffffff
    style Gateway fill:#1168bd,stroke:#0b4884,color:#ffffff
    style OrdersMS fill:#438dd5,stroke:#2e6295,color:#ffffff
    style ProviderMS fill:#438dd5,stroke:#2e6295,color:#ffffff
    style AuthMS fill:#438dd5,stroke:#2e6295,color:#ffffff
    style NotificationsMS fill:#438dd5,stroke:#2e6295,color:#ffffff

Catálogo de Módulos de Funcionalidad

Funcionalidad	Dominio	Capacidades Clave	Roles de Usuario	Rutas	Fuente
auth	Autenticación	Login, registro, recuperación de contraseña	Todos (público)	`/auth/sign-in`, `/auth/sign-up-client`, `/auth/sign-up-provider`	`paths.auth.*`
orders	Gestión de Órdenes	Ciclo de vida de órdenes, asignaciones, reportes	Admin, Agente	`/dashboard/orders`, `/dashboard/orders/details/:orderID`	`paths.app.orders`, `paths.app['order-details']`
marketplace	Subastas	Sistema de subastas, ofertas, cotizaciones	Admin, Agente, Proveedor	`/dashboard/marketplace/auctions`, `/dashboard/marketplace/auctions-provider`	`paths.app['marketplace-auction-list']`, `paths.app['marketplace-auction-list-provider']`
providers	Gestión de Proveedores	Seguimiento de trabajos, facturas, perfil, documentos	Proveedor	`/dashboard/providers/works`, `/dashboard/providers/invoices`, `/dashboard/providers/profile`	`paths.app.provider`, `paths.app['provider-invoices']`, `paths.app['provider-profile']`
assets	Gestión de Activos	Ciclo de vida de activos, seguimiento de errores	Admin, Agente	`/dashboard/assets`, `/dashboard/errors`	`paths.app.assets`, `paths.app['assets-error']`
clients	Portal de Clientes	Seguimiento de órdenes, aprobación de cotizaciones, calificaciones	Cliente	`/dashboard/client/orders`	`paths.app['my-orders-client']`
users	Gestión de Usuarios	Gestionar clientes, proveedores, personal	Admin, Agente	`/dashboard/users/clients`, `/dashboard/users/providers`, `/dashboard/users/management`	`paths.app.users`, `paths.app['users-providers']`, `paths.app['users-management']`
dashboard	Analíticas	KPIs, métricas, insights de negocio	Admin, Agente	`/dashboard`	`paths.app.dashboard`
contracts-and-policies	Contratos (Contador)	Gestión de contratos/pólizas para contadores	Contador	`/dashboard/accountant/contracts`	`paths.app['contracts-and-policies']`
admin-contracts-and-policies	Contratos (Admin)	Gestión de contratos/pólizas para admins	Admin, Agente	`/dashboard/contracts`	`paths.app['admin-contracts-and-policies']`
guarantees-contracts-and-policies	Contratos (Garantías)	Gestión de contratos/pólizas para garantías	Garantías	`/dashboard/guarantees/contracts-policies`	`paths.app['guarantees-contracts-and-policies']`
accounting	Contabilidad	Seguimiento financiero, pagos	Admin, Agente	`/dashboard/accountant/accounting`	`paths.app.accounting`
monitoring-panel	Monitoreo	Seguimiento de mensajes	Admin, Agente, Cliente	`/dashboard/monitoring-panel`	`paths.app['monitoring-panel']`

Stack Tecnológico

Categoría	Tecnología	Versión	Propósito
Framework	React	19.1.0	Librería de UI
Lenguaje	TypeScript	5.8.3	JavaScript con tipos
Herramienta de Build	Vite	6.3.5	Build rápido y servidor de desarrollo
Compilador	SWC	-	Compilación rápida de TypeScript/JSX
Estilos	Tailwind CSS	4.1.6	CSS utility-first
Ruteo	React Router	6.30.0	Ruteo del lado del cliente
Estado del Servidor	@tanstack/react-query	5.76.0	Gestión de estado del servidor
Estado del Cliente	Zustand	5.0.4	Gestión de estado del cliente
Formularios	React Hook Form	7.56.3	Manejo de formularios
Validación	Zod	3.23.8	Validación de esquemas
Cliente HTTP	Axios	1.9.0	Solicitudes API
Componentes UI	Radix UI	-	Primitivos accesibles
Iconos	Lucide React	0.510.0	Librería de iconos
Gráficos	Recharts	2.15.3	Visualización de datos
Pruebas	Vitest	3.1.3	Pruebas unitarias
Pruebas E2E	Playwright	1.52.0	Pruebas de extremo a extremo
Calidad de Código	ESLint	9.25.0	Linting
Formateo	Prettier	3.5.3	Formateo de código
Git Hooks	Husky	9.1.7	Hooks de pre-commit
Gestor de Paquetes	pnpm	10.15.0	Gestor de paquetes rápido

Principios de Arquitectura

1. Organización Basada en Funcionalidades (Bulletproof React)

Cada funcionalidad es auto-contenida con sus propios componentes, hooks, llamadas API y tipos. Esto promueve:

Modularidad: Las funcionalidades pueden desarrollarse independientemente
Escalabilidad: Fácil agregar nuevas funcionalidades sin afectar las existentes
Mantenibilidad: Límites claros entre funcionalidades
Colaboración en Equipo: Múltiples desarrolladores pueden trabajar en diferentes funcionalidades

2. Separación de Responsabilidades

Componentes UI: Solo lógica de presentación (components/ui/)
Lógica de Negocio: Encapsulada en hooks personalizados (features/*/hooks/)
Obtención de Datos: Aislada en archivos de API (features/*/api/)
Gestión de Estado: Clara distinción entre estado del servidor (React Query) y estado del cliente (Zustand)

3. Seguridad de Tipos con TypeScript en Modo Estricto

Todo el código está estrictamente tipado
No hay tipos any implícitos
Detección de errores en tiempo de compilación
Mejor soporte de IDE y autocompletado

4. Composición de Componentes sobre Prop Drilling

Los componentes se componen de componentes más pequeños
Se usa contexto o gestión de estado para estado compartido
Las props se mantienen mínimas y explícitas

5. Separación de Estado del Servidor vs Estado del Cliente

Estado del Servidor (React Query): Datos de la API (órdenes, usuarios, activos)
Estado del Cliente (Zustand): Estado de UI, preferencias de usuario, datos temporales
Diferentes preocupaciones requieren diferentes soluciones

6. Lazy Loading para Rendimiento

Todas las rutas se cargan de forma diferida
División de código por funcionalidad
Tamaño de bundle inicial más pequeño
Tiempo más rápido para interactividad

7. Control de Acceso Basado en Roles (RBAC)

Capa de autenticación con JWT
Verificaciones de autorización en rutas y componentes
Cuatro roles de usuario distintos con diferentes capacidades
Seguro por defecto

8. Error Boundaries para Resiliencia

Error boundaries en todas las rutas
Manejo de errores graceful
Mensajes de error amigables para el usuario
Registro de errores para depuración

Referencias Cruzadas

Documentación Detallada:

Módulos de Funcionalidades - Documentación detallada de las 11 funcionalidades
Librería de Componentes - Catálogo completo de componentes y sistema de diseño
Gestión de Estado - Patrones de React Query, Zustand, estado en URL
Ruteo y Navegación - Configuración de rutas y navegación
Autenticación - Flujo de autenticación e implementación RBAC

Integración con Backend:

API Gateway - Configuración del API Gateway
Microservicios Backend - Arquitectura del backend

Guías de Desarrollo:

Guía de Desarrollo Frontend - Flujos de trabajo de desarrollo y mejores prácticas

Inicio Rápido

Configuración de Desarrollo

# Instalar dependencias
pnpm install

# Iniciar servidor de desarrollo
pnpm dev

# Abrir navegador en http://localhost:5173

Build para Producción

# Build para producción
pnpm build

# Vista previa del build de producción
pnpm preview

Pruebas

# Ejecutar pruebas unitarias
pnpm test

# Ejecutar pruebas E2E
pnpm test:e2e

# Ejecutar pruebas con cobertura
pnpm test:coverage

Calidad de Código

# Lint del código
pnpm lint

# Formatear código
pnpm format

# Verificación de tipos
pnpm type-check

Referencia Rápida de Estructura del Proyecto

¿Necesitas agregar una nueva funcionalidad? → src/features/[nombre-funcionalidad]/
¿Necesitas agregar un componente UI? → src/components/ui/
¿Necesitas agregar una ruta? → src/app/router.tsx
¿Necesitas configurar la API? → src/lib/api-client.ts
¿Necesitas agregar tipos? → src/types/
¿Necesitas agregar utilidades? → src/utils/

Referencias:

algesta-dashboard-react/package.json
algesta-dashboard-react/vite.config.ts
algesta-dashboard-react/tsconfig.json
algesta-dashboard-react/AGENTS.md
Estructura de directorios de exploración del código