Panel de Administracion (nvito-admin)

Tabla de Contenidos

1. Estructura del Proyecto
2. Mapa de Rutas
3. Sub-rutas de Evento
4. Componentes Clave
5. Arquitectura del API Client
6. Server Actions
7. Gestion de Estado
8. Validacion de Formularios
9. Sistema de UI
10. Seguridad
11. Performance
12. Accesibilidad
13. Testing

Estructura del Proyecto

nvito-admin es una aplicacion Next.js 16 con App Router que sirve como panel de administracion para organizadores de eventos. Es el frontend principal donde los usuarios gestionan eventos, invitados, invitaciones, mesas, RSVP, comunicaciones y mas.

Stack Tecnologico

Estructura de Directorios

nvito-admin/
├── src/
│   ├── app/
│   │   ├── (auth)/                    # Rutas de autenticacion
│   │   │   ├── sign-in/[[...sign-in]]/
│   │   │   └── sign-up/[[...sign-up]]/
│   │   └── (dashboard)/              # Rutas del dashboard
│   │       ├── layout.tsx             # Layout con sidebar
│   │       ├── page.tsx               # Dashboard principal
│   │       ├── error.tsx              # Error boundary
│   │       ├── events/               # Gestion de eventos
│   │       ├── admin/                # Panel super admin
│   │       └── organization/         # Config organizacion
│   ├── components/
│   │   ├── ui/                       # 41+ componentes shadcn/ui
│   │   ├── admin/                    # Componentes de admin
│   │   ├── visual-editor/            # Editor visual Artisan
│   │   └── organizations/            # Componentes de organizacion
│   ├── hooks/                        # Hooks globales
│   ├── lib/
│   │   ├── api/
│   │   │   ├── client.ts             # API Client base (con getValidated)
│   │   │   ├── response-schemas.ts   # Schemas Zod para response validation
│   │   │   ├── services/             # 34 archivos de servicio
│   │   │   └── hooks/queries/        # React Query hooks (34+ archivos)
│   │   ├── actions/                  # 17 server actions con Zod validation
│   │   │   └── types.ts              # ActionResult discriminated union
│   │   ├── hooks/                    # Hooks de dominio
│   │   ├── validations/              # 15 esquemas Zod
│   │   └── themes/                   # Temas del admin
│   └── providers/                    # Context providers
├── config/environments/              # Archivos .env por ambiente
└── scripts/                          # Scripts de utilidad

Mapa de Rutas

El siguiente diagrama muestra todas las rutas de la aplicacion organizadas por grupo de layout:

Descripcion de Rutas

Sub-rutas de Evento

Cada evento (/events/[eventId]/) expone 21 sub-rutas que cubren la gestion completa:

Componentes Clave

Event Wizard

El wizard de creacion de eventos (/events/new) guia al usuario a traves de un flujo multi-paso para configurar su evento. Incluye seleccion de tipo de evento, datos basicos, ubicaciones y plantilla de invitacion.

Editor Visual Artisan (iframe-based)

El editor visual Artisan permite a los usuarios personalizar sus invitaciones de forma interactiva. Se integra mediante un iframe que carga el editor con comunicacion bidireccional entre el admin y el editor. El hook use-artisan-invitation-editor.ts gestiona el estado y la comunicacion con el iframe.

Invitaciones Externas

El modulo de invitaciones soporta dos origenes (InvitationSource): INTERNAL (editor visual + IA) y EXTERNAL (HTML subido por el usuario). La pagina de creacion (/invitations/new) muestra 2 opciones al mismo nivel: "Elegir Template" y "Cargar HTML Existente".

Componentes principales:

• ExternalUploadForm — Formulario drag & drop para subir archivo .html/.htm (max 5 MB). Campos opcionales: SEO title y description. Valida extension y tamano en cliente antes de enviar.
• ExternalInvitationDetail — Vista de detalle para invitaciones externas (early return, sin editor visual). Muestra preview en iframe, estado con badge naranja "Externa", y acciones contextuales segun el estado.
• ReuploadExternalDialog — Dialog modal para reemplazar el HTML (solo en estado IN_CONSTRUCTION). Advierte que la operacion es irreversible.
• DownloadExternalButton — Descarga el HTML original desde la BD como archivo .html.
• InvitationsTable — Muestra badge naranja "Externa" cuando source === EXTERNAL.

Acciones disponibles por estado:

Flujo de datos:

• Service: external-invitations.ts (3 metodos: upload, reupload, download)
• Actions: external-invitations.ts (3 server actions con validacion Zod)
• Schemas: uploadExternalInvitationSchema, reuploadExternalInvitationSchema en invitation.ts

RSVP Analytics (Recharts)

La seccion de analitica utiliza Recharts para mostrar graficas de:

• Tendencias de confirmaciones en el tiempo
• Distribucion de respuestas (confirmados / pendientes / rechazados)
• Vistas de la invitacion por dispositivo y navegador
• Timeline de actividad

Gestion de Clientes (Admin)

La pagina /admin/clients permite gestionar la relacion comercial con los clientes que contratan eventos. Es accesible para usuarios con permisos de Admin Panel (Super Admin y Platform Admin).

Componentes principales:

• ClientsTable — Tabla con paginacion server-side, filtros por estado (ClientStatus), tipo (ClientType), busqueda por nombre/email/telefono, y ordenamiento en columnas. Incluye columna de organizacion visible para Super Admin.
• ClientFormDialog — Dialog con React Hook Form + Zod para crear y editar clientes. Secciones: contacto, clasificacion, datos fiscales (colapsable), adquisicion, asignacion de responsable y notas.
• MemberSelector — Selector de miembros activos de una organizacion para asignar un responsable (assignedToId). Carga usuarios via GET /admin/users?organizationId=x.
• OrganizationSelector — Selector de organizacion para Super Admin (elige tenant al crear un cliente).
• ClientStatusBadge / ClientTypeBadge — Badges visuales para estado y tipo de cliente.

Flujo de datos:

• Hooks: useClients(params), useClient(id), useCreateClient(), useUpdateClient(), useDeleteClient()
• Server Actions: createClientAction, updateClientAction, deleteClientAction
• Validacion: schema Zod createClientSchema con validacion de RFC mexicano (/^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{3}$/i)

Gestion de Mesas (dnd-kit)

El modulo de mesas usa @dnd-kit (core + sortable) para permitir arrastrar y soltar invitados entre mesas, con vista visual del layout.

Comunicaciones (/communications)

La pagina de comunicaciones es una de las mas completas del admin, organizada en 5 tabs:

1. Enviar Mensaje — 5 cards de accion que abren wizards multi-paso:

Cada wizard incluye: seleccion de canal, filtrado avanzado de destinatarios, estimacion en tiempo real, preview del mensaje, deteccion de duplicados y confirmacion final. El componente CampaignWizardShell proporciona una shell reutilizable con prop disabledHint para indicar al usuario por que no puede avanzar al siguiente paso.

2. Historial — Lista de campanas con filtros client-side:

• Filtros: tipo de campana, estado, canal, busqueda por nombre
• Columnas ordenables: fecha, nombre, tipo, estado, destinatarios, enviados
• Vista detalle con 4 stat cards (destinatarios, enviados, entregados, fallidos) y porcentajes
• Tabla de mensajes individuales con status badges y boton de retry para fallidos
• Reutiliza componentes estandar: useTableFilters, useSortableTable, FilterBar, SortableHeader, EmptyState

3. Estadisticas — Dashboard con metricas agregadas:

• Cards principales: Enviados, Entregados, Abiertos, Fallidos (con porcentajes)
• Desglose por canal (Email, WhatsApp)
• Desglose por tipo de campana

4. Plantillas — Gestion de templates de comunicacion:

• CRUD con editor WYSIWYG basado en Tiptap (toolbar, variables, image placeholder)
• Filtros por tipo de campana y estado
• Acciones: duplicar, archivar, marcar como default
• 12 variables disponibles (nombre, evento, fecha, hora, ubicacion, etc.)

5. Automatizacion — Workflows automaticos:

• 6 triggers: GUEST_ADDED, RSVP_CONFIRMED, RSVP_DECLINED, DAYS_BEFORE_EVENT, EVENT_DAY, POST_EVENT
• Toggle activo/pausado con Switch
• Conteo de ejecuciones y ultima ejecucion
• Crear, editar, eliminar workflows

Componentes (20+ archivos en src/components/communications/):

• 5 dialog wizards: send-invitation-dialog, send-reminder-dialog, send-message-dialog, send-save-the-date-dialog, send-rsvp-chatbot-dialog
• Listas y detalle: campaign-list, campaign-detail, communication-stats
• Templates: template-list, template-editor-dialog, template-selector
• Workflows: workflow-list, workflow-create-dialog
• Componentes compartidos: recipient-selector-advanced, guest-search-selector, channel-selector, message-preview, send-confirmation-step, image-upload-field, campaign-wizard-shell
• Editor rico: template-rich-editor/ (subdirectorio con 5 archivos: editor, toolbar, hooks, extensions)

Flujo de datos:

• Services: communications.service.ts (19 metodos), communication-templates.service.ts (7 metodos)
• Hooks: use-communications.ts (5 queries + 3 mutations), use-communication-templates.ts (2 queries + 4 mutations)
• Actions: communications.ts (13 server actions con validacion Zod)
• Validacion: communication.ts (16 schemas Zod), communication-template.ts
• Types: communication.ts (352 lineas — campanas, mensajes, workflows, DTOs), communication-template.ts (78 lineas)

Arquitectura del API Client

El sistema de comunicacion con el backend sigue una arquitectura en capas claramente separada:

ApiClient (client.ts)

Clase base que encapsula todas las operaciones HTTP:

• Metodos: get, post, put, patch, delete, upload
• Autenticacion: Token Bearer opcional en cada request
• Base URL: Configurable via NEXT_PUBLIC_API_URL (default: http://localhost:3000/v1)
• Error handling: Clase ApiError personalizada con statusCode y message
• Cache: Deshabilitado para API calls (cache: 'no-store')
• Upload: Soporte para multipart/form-data sin Content-Type header (lo genera el browser)

Services (34 archivos)

Cada dominio tiene un archivo de servicio dedicado que encapsula los endpoints:

React Query Hooks (34+ hooks)

Ubicados en src/lib/hooks/queries/, cada hook encapsula:

• Queries (useQuery): Lectura de datos con cache automatico
• Mutations (useMutation): Operaciones de escritura con invalidacion de cache
• Query Keys: Sistema centralizado en keys.ts para invalidacion predecible

Server Actions

Arquitectura de Server Actions

El proyecto utiliza Next.js Server Actions como capa de mutacion entre el frontend y la API. Todas las acciones del servidor siguen un patron consistente:

1. Autenticacion: Obtienen el token de Clerk via auth().getToken()
2. Validacion: Validan inputs con schemas Zod antes de llamar a la API
3. Ejecucion: Llaman al API Client con el token de autenticacion
4. Resultado: Retornan ActionResult<T> tipado (discriminated union)
5. Revalidacion: Ejecutan revalidatePath() para actualizar cache de Next.js

ActionResult (Error Handling)

Todas las server actions retornan un tipo ActionResult<T> que es una discriminated union:

type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };

Esto garantiza que el consumer siempre maneje ambos casos (exito y error) de forma type-safe, sin excepciones no controladas.

Server Actions Disponibles (17 archivos)

Todas las acciones tienen validacion Zod en la frontera y tests unitarios co-localizados.

Gestion de Estado

React Query 5 + SWR

La aplicacion usa un enfoque hibrido para gestion de estado del servidor:

• React Query 5 (@tanstack/react-query): Se usa como sistema principal para la mayoria de queries y mutations
• SWR: Se usa en casos puntuales de revalidacion reactiva (tablas, invitaciones)

Query Keys Factory

El archivo keys.ts centraliza todas las claves de cache siguiendo el patron de factory:

// Ejemplo de estructura de keys
queryKeys.guests.all(eventId)         // ['guests', eventId]
queryKeys.guests.list(eventId, params) // ['guests', eventId, 'list', params]
queryKeys.guests.detail(eventId, id)   // ['guests', eventId, id]

Dominios cubiertos por el Query Key Factory (19 dominios):

• admin (users, roles, invitations, health)
• contracts, clients, packages, organizations, sales
• guests, guestGroups, tables, qrPasses
• communications, analytics, rsvps, media
• invitations, organization, permissions
• events, dashboard, giftRegistry, backgroundMusic
• accommodation, locations, itinerary
• collaborators, team, customDomain
• eventTypes, templates, templatesAdmin
• mobileAccess

Invalidacion de Cache

Al completar una mutation, se invalidan selectivamente las queries relacionadas usando queryClient.invalidateQueries() con las keys del factory. Esto asegura que los datos mostrados siempre estan actualizados.

Validacion de Formularios

React Hook Form + Zod

Todos los formularios usan React Hook Form con Zod como resolver de validacion a traves de @hookform/resolvers.

Esquemas de Validacion (15 archivos)

Todos los esquemas tienen tests unitarios co-localizados en __tests__/.

Sistema de UI

shadcn/ui (41+ componentes)

La aplicacion utiliza shadcn/ui como sistema de componentes base, construido sobre Radix UI para accesibilidad y Tailwind CSS v4 para estilos.

Componentes UI Disponibles

Componentes Custom

Ademas de shadcn/ui, el proyecto incluye componentes personalizados:

• filter-bar.tsx: Barra de filtros reutilizable para tablas
• search-input.tsx: Input de busqueda con debounce
• service-page-header.tsx: Header estandar para paginas de servicio
• table-skeleton.tsx: Skeleton loader para tablas
• empty-state.tsx: Estado vacio con icono y accion
• sortable-header.tsx: Header de columna con ordenamiento
• money-input.tsx: Input especializado para montos monetarios
• package-badge.tsx: Badge visual para planes/paquetes
• time-ago.tsx: Componente de tiempo relativo
• highlight-text.tsx: Resaltado de texto de busqueda

Modo Oscuro

El modo oscuro se implementa con next-themes y el hook personalizado use-admin-theme.ts. Todos los componentes de shadcn/ui soportan dark mode de forma nativa a traves de las variables CSS de Tailwind.

Iconos

Se usa Lucide React (lucide-react) como libreria de iconos. Los componentes del itinerario usan un mapa explicito de iconos (itinerary-icons.ts) en vez de barrel imports para optimizar bundle size.

Animaciones

Framer Motion se utiliza para animaciones de transicion en:

• Apertura y cierre de modales
• Transiciones entre pasos del wizard
• Animaciones de drag-and-drop
• Microinteracciones de UI

Seguridad

Autenticacion con Clerk

La autenticacion se gestiona via Clerk 6 (@clerk/nextjs):

• Clerk Provider: Contexto de autenticacion a nivel de layout raiz
• auth() en Server Actions: Cada action obtiene el token JWT de Clerk para llamadas a la API
• Proteccion de rutas: El layout del dashboard verifica autenticacion; las rutas de auth (/sign-in, /sign-up) son publicas

Content Security Policy (CSP)

Headers CSP configurados en next.config.ts con directivas adaptadas a los servicios usados:

Response Validation en Runtime

Los servicios criticos utilizan apiClient.getValidated() que valida las respuestas del API con schemas Zod en runtime, proporcionando defense-in-depth contra responses inesperadas:

• events.ts — Valida estructura de eventos
• guests.service.ts — Valida arrays de invitados
• organizations.service.ts — Valida contexto de organizacion

Performance

React Compiler

El proyecto tiene React Compiler habilitado (reactCompiler: true en next.config.ts), lo que proporciona memoizacion automatica de componentes y hooks sin necesidad de React.memo, useMemo o useCallback manuales.

Build Optimization

Accesibilidad

Tablas

Las 6 tablas principales implementan atributos ARIA para accesibilidad:

• aria-label: Describe el proposito de la tabla (ej: "Lista de invitados")
• aria-sort: Indica la direccion de ordenamiento en headers con SortableHeader (ascending/descending/none)

Navegacion por teclado

Los componentes interactivos tipo card soportan navegacion por teclado:

• role="button" en cards clickeables
• onKeyDown para Enter y Space
• Focus visible en todos los elementos interactivos

ARIA Labels

Los botones de icono (sin texto visible) incluyen aria-label descriptivo para lectores de pantalla.

Testing

Metricas

Cobertura por Area

Organizacion de Tests

Los tests estan co-localizados en directorios __tests__/ junto al codigo fuente:

src/lib/api/services/__tests__/      # Tests de servicios
src/lib/actions/__tests__/           # Tests de server actions
src/lib/validations/__tests__/       # Tests de schemas Zod
src/lib/hooks/queries/__tests__/     # Tests de React Query hooks
src/components/*/__tests__/          # Tests de componentes

Patron de Tests de Server Actions

// Ejemplo: test de una server action
it('retorna error sin token', async () => {
  mockAuth.mockResolvedValueOnce({
    getToken: vi.fn().mockResolvedValue(null),
  } as any);

  const result = await someAction({ eventId: 'evt-1' });
  expect(result.success).toBe(false);
});

Arquitectura SOLID

Descomposicion de Componentes

Los componentes complejos siguen el principio de responsabilidad unica (SRP) mediante extraccion de hooks y sub-componentes:

Contract Form Dialog (~400 lineas orquestador):

• contracts/hooks/use-contract-calculations.ts — Calculos de precios (useMemo)
• contracts/hooks/use-contract-form-state.ts — Estado del formulario (useState + useEffect)
• contracts/contract-event-search.tsx — Busqueda de evento
• contracts/contract-pricing-section.tsx — Seccion de precios
• contracts/contract-payment-section.tsx — Seccion de pago

Groups Manager (~250 lineas orquestador):

• groups/hooks/use-groups-manager.ts — Estado y handlers
• groups/group-card.tsx — Card individual de grupo
• groups/group-dialogs.tsx — Dialogs compound (crear, editar, eliminar, asignar)

Scripts de Desarrollo

# Desarrollo local (puerto 5050)
npm run dev

# Cambiar ambiente
npm run env:dev           # Desarrollo local
npm run env:dev-remote    # API remota desarrollo
npm run env:test-remote   # API remota testing

# Build de produccion
npm run build

# Desarrollo con Bitwarden Secrets Manager
npm run dev:bws

Referencias

• Codigo fuente: nvito-admin/
• API Client: src/lib/api/client.ts
• Response Schemas: src/lib/api/response-schemas.ts
• Services: src/lib/api/services/
• Server Actions: src/lib/actions/
• ActionResult: src/lib/actions/types.ts
• Query Hooks: src/lib/hooks/queries/
• Query Keys: src/lib/hooks/queries/keys.ts
• Validaciones: src/lib/validations/
• Componentes UI: src/components/ui/
• CSP Config: next.config.ts

Ultima actualizacion: Marzo 2026 — Incluye modulo de Comunicaciones actualizado