App Móvil

Estructura del Proyecto

nvito-client es una aplicación móvil nativa para iOS y Android construida con React Native y Expo. Es el 4to proyecto del ecosistema Nvito y complementa las aplicaciones web existentes ofreciendo una experiencia nativa optimizada para el día del evento.

Stack Tecnológico

Configuración de Plataforma

Estructura de Directorios

Navegación y Rutas

La app usa Expo Router v6 con navegación file-based. La estructura de navegación se adapta según el rol del usuario autenticado (HOST o GUEST).

Diagrama de Navegación

Descripción de Rutas

Tabs del Anfitrión

Tabs del Invitado

Autenticación Móvil

La app usa un sistema de autenticación independiente de Clerk, basado en JWT con un secreto dedicado (MOBILE_JWT_SECRET). Esto permite que los invitados accedan sin necesidad de crear una cuenta.

Flujo de Autenticación del Anfitrión

Flujo de Autenticación del Invitado

Almacenamiento de Sesión

Auto-refresh de Tokens

El AuthContext programa automáticamente la renovación del JWT:

1. Al hacer login, se programa un timer basado en expiresIn del JWT
2. El refresh se ejecuta cuando quedan < 2 minutos de vida
3. Al volver del background, se programa un refresh conservador inmediato
4. La rotación de refresh tokens garantiza que cada token solo se use una vez

JWT Payload

// HOST
{ sub: eventId, role: "HOST", userId: string, sessionId: string }

// GUEST
{ sub: eventId, role: "GUEST", guestId: string, sessionId: string }

Pantallas del Anfitrión (HOST)

Dashboard

Pantalla principal del anfitrión con estadísticas del evento en tiempo real.

• Polling cada 30 segundos para datos en vivo
• Pull-to-refresh manual
• Layout adaptativo: cards en grid para tablet

Invitados

Lista completa de invitados con búsqueda y filtros.

• FlatList virtualizada para rendimiento con listas grandes
• Layout responsive: 2 columnas en tablet

Detalle de Invitado (Bottom Sheet)

Al tocar un GuestCard, se abre un modal slide-up con el detalle completo del invitado (useGuestDetail hook). Secciones:

Componentes: guests/guest-detail-sheet.tsx, guests/guest-card.tsx (pressable).

Scanner (QR Check-in)

Scanner QR fullscreen para registrar la asistencia de invitados.

Check-in Manual por Nombre

Botón de búsqueda en el header del Scanner que abre un modal slide-up para registrar invitados sin necesidad de escanear QR:

Componentes: scanner/manual-check-in-sheet.tsx, scanner/hooks/use-manual-search.ts.

Mesas (HOST)

Pantalla read-only para visualizar la distribución y asignación de mesas del evento. La gestión (crear, editar, asignar) se realiza exclusivamente desde el admin web.

Componentes: tables.tsx (orquestador), tables/stats-summary.tsx, tables/table-card.tsx, tables/table-list.tsx, tables/table-visual.tsx, tables/table-plan.tsx, tables/table-detail-sheet.tsx.

Memorias

Vista unificada que fusiona Galería, Audio Guestbook y Mensajes en una sola pantalla con segmented control e infinite scroll. Accesible desde el menú "Más", reemplaza los 3 items separados.

Segmento Fotos

Segmento Audios

Segmento Mensajes

Componentes: memorias.tsx (orquestador), memorias/segmented-control.tsx, memorias/memorias-gallery.tsx, memorias/memorias-audios.tsx, memorias/memorias-messages.tsx, memorias/photo-thumbnail.tsx, memorias/photo-viewer.tsx, memorias/message-card.tsx.

Itinerario (HOST)

Programa del evento con timeline visual idéntico al del invitado, accesible desde el menú "Más". Reutiliza los mismos componentes compartidos (src/components/itinerary/).

Componentes compartidos HOST/GUEST: src/components/itinerary/timeline-item.tsx (exporta isCurrentItem(), isPastItem(), TimelineItem), src/components/itinerary/location-card.tsx (LocationCard con icono por tipo de ubicación).

Mesa de Regalos (HOST)

Vista read-only del estado de la mesa de regalos del evento. Accesible desde el menú "Más". No incluye widget de Stripe ni botón de contribución (el HOST no dona a su propio fondo).

Componentes: gift-registry.tsx (orquestador), gift-registry/cash-fund-progress.tsx, gift-registry/registry-item-card.tsx.

Pantallas del Invitado (GUEST)

Home

Pantalla principal del invitado con bienvenida personalizada, pase QR y countdown al evento.

Itinerario

Programa del evento con timeline visual. Las LocationCards incluyen información enriquecida.

Interactuar

Pantalla con secciones condicionales (service gating) para que el invitado interactúe con el evento. Cada tipo de contenido tiene un límite por invitado.

Los límites se consultan mediante endpoints dedicados (/my-count) que retornan { count, limit }. Cuando el invitado alcanza el límite, el botón de acción se deshabilita con un mensaje informativo.

Hospedaje

Pantalla accesible desde "Mas" con toda la información de hospedaje del evento.

Más

Menú con opciones condicionales según servicios habilitados.

Service Gating

Las secciones y pantallas del invitado se muestran condicionalmente según los servicios contratados para el evento. El sistema usa dos mecanismos complementarios:

• useEventServices(): Hook que obtiene la lista de servicios habilitados del evento. Si los servicios aún no se han cargado, se muestran todas las secciones como fallback.
• useRequireService(serviceNames): Guard hook que verifica si al menos uno de los servicios requeridos está habilitado. Retorna { allowed, isLoading } para proteger pantallas accesibles via deep link o navegación directa.

Las vistas completas (Galería, Audio Guestbook, Mensajes, Mesa de Regalos, Hospedaje) solo se renderizan si el servicio correspondiente está contratado en el evento.

Arquitectura del API Client

El sistema de comunicación con el backend sigue una arquitectura en capas, similar a nvito-admin pero adaptada para autenticación móvil.

API Client (client.ts)

Fetch wrapper que encapsula todas las operaciones HTTP:

• Métodos: get<T>, post<T>, patch<T>, delete<T>
• Base URL: Configurable via EXPO_PUBLIC_API_URL (default: http://localhost:3000/v1)
• Auth interceptor: Inyecta Bearer token desde SecureStore automáticamente
• Auto-refresh: Si recibe 401, intenta renovar el JWT con el refresh token
• Error handling: Clase ApiError con statusCode y message

Services (7 archivos)

Prefijo de Endpoints Móviles

Todos los endpoints consumidos por la app móvil usan el prefijo /v1/mobile/ y están protegidos por el MobileAuthGuard (independiente de Clerk). Los endpoints son wrappers ligeros que reutilizan los servicios existentes del backend.

Endpoints de Media Móvil

Gestión de Estado

React Query 5

La app usa TanStack React Query como único sistema de gestión de estado del servidor:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,       // 5 min stale
      gcTime: 24 * 60 * 60 * 1000,    // 24h en cache
      retry: 2,
    },
  },
});

Query Key Factory

El archivo keys.ts centraliza todas las claves de cache:

queryKeys.events.detail(eventId)          // ['events', eventId]
queryKeys.events.stats(eventId)           // ['events', eventId, 'stats']
queryKeys.guests.list(eventId, params)    // ['guests', eventId, 'list', params]
queryKeys.media.gallery(eventId, page)    // ['media', eventId, 'gallery', page]
queryKeys.media.myPhotoCount(eventId)     // ['media', eventId, 'my-photo-count']
queryKeys.media.audioMessages(eventId)    // ['media', eventId, 'audio-messages']
queryKeys.media.myAudioCount(eventId)     // ['media', eventId, 'my-audio-count']
queryKeys.media.messages(eventId)         // ['media', eventId, 'messages']
queryKeys.media.myMessages(eventId)       // ['media', eventId, 'my-messages']
queryKeys.media.myMessageCount(eventId)   // ['media', eventId, 'my-message-count']
queryKeys.media.giftRegistry(eventId)     // ['media', eventId, 'gift-registry']

Hooks de React Query

AuthContext (Descomposición SOLID)

El contexto de autenticación fue descompuesto siguiendo SRP en 4 archivos con responsabilidad única:

El contexto gestiona el estado de sesión con un useReducer:

Acciones del reducer:

• RESTORE_SESSION — Restaurar sesión desde SecureStore al montar
• LOGIN — Login exitoso (host o guest)
• LOGOUT — Cerrar sesión y limpiar tokens
• TOKENS_REFRESHED — Actualizar tokens tras refresh
• SET_LOADING — Cambiar estado de carga

QR Scanner y Check-in

Flujo Completo de Check-in

Datos del QR

Cada invitado tiene un QR único que contiene su guestId. Al escanear:

1. La app extrae el guestId del contenido del QR
2. Envia POST /v1/mobile/events/:id/check-in con el guestId
3. El API verifica que el invitado pertenece al evento y no está ya registrado
4. Si el invitado tiene groupSize > 1, se muestra un modal para seleccionar cuántos asisten

Check-in Parcial (Grupos)

Cuando un invitado tiene acompañantes, el scanner muestra:

• Nombre del invitado y total del grupo
• Stepper numérico para seleccionar asistentes
• Rango: 1 hasta groupSize
• Soporte para re-escaneo (agregar más personas después)

Media: Galería y Audio Guestbook

Upload de Fotos

Grabación de Audio

Límites de Media

Los límites por invitado se verifican tanto en el frontend (contadores visuales, botón deshabilitado) como en el backend (validación server-side que retorna 403 al exceder el límite).

Push Notifications

Registro de Push Token

Configuración del Handler

La app configura las notificaciones en foreground para mostrar alertas, sonido, badge y banners:

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: true,
    shouldShowBanner: true,
    shouldShowList: true,
  }),
});

Eventos que Disparan Push

Canal de Android

Para Android, se configura un canal de notificaciones dedicado:

Notifications.setNotificationChannelAsync('default', {
  name: 'Nvito',
  importance: Notifications.AndroidImportance.HIGH,
  vibrationPattern: [0, 250, 250, 250],
  lightColor: '#7C3AED',
});

Deep Linking

La app soporta deep links para acceso directo de invitados.

URIs Soportados

Configuración

iOS — Associated Domains:

"associatedDomains": ["applinks:nvito.app"]

Android — Intent Filters:

"intentFilters": [{
  "action": "VIEW",
  "autoVerify": true,
  "data": [{
    "scheme": "https",
    "host": "nvito.app",
    "pathPrefix": "/join"
  }],
  "category": ["BROWSABLE", "DEFAULT"]
}]

Custom Scheme:

"scheme": "nvito"

Design System

Fuente Única de Verdad: src/theme/colors.ts

Todos los colores de la aplicación están centralizados en un único archivo src/theme/colors.ts exportado como as const para type safety. El archivo tailwind.config.js importa estos colores directamente, eliminando la duplicación.

Antes: ~130 instancias de colores hex hardcodeados dispersos en 12+ archivos. Después: 0 colores hardcodeados; todos referencian colors.* desde el theme.

Paleta de Colores

Integración con Tailwind

// tailwind.config.js
const { colors } = require('./src/theme/colors');
module.exports = {
  theme: { extend: { colors } },
};

NativeWind (Tailwind CSS para React Native)

La app usa NativeWind v4 que permite usar clases de Tailwind CSS directamente en componentes React Native:

<View className="flex-1 bg-background p-4">
  <Text className="text-xl font-heading text-text-primary">Titulo</Text>
  <Text className="text-sm text-text-secondary mt-1">Descripción</Text>
</View>

Tipografía

Responsive / Tablet

La app detecta si se ejecuta en tablet mediante el hook useResponsive() y adapta los layouts:

Iconografía

Se usa Ionicons via @expo/vector-icons con estilo outline consistente en toda la app.

Variables de Entorno

Arquitectura SOLID

El proyecto aplica Single Responsibility Principle (SRP) sistemáticamente. Las pantallas grandes fueron descompuestas en orquestadores livianos + sub-componentes + hooks custom.

Descomposición de Pantallas

Reducción total: 70% menos líneas en archivos orquestadores, distribuidas en componentes enfocados y reutilizables.

Descomposición del AuthContext

Validación con Zod

El proyecto incluye schemas Zod v4 para validar respuestas de API en runtime, complementando la seguridad de tipos de TypeScript en compilación.

Schemas Disponibles

Cada schema tiene tests que verifican datos válidos, campos faltantes y tipos incorrectos.

Testing

El proyecto cuenta con 32 suites de prueba y 257 tests individuales, todos con 100% de tasa de éxito.

Framework

Mocks Globales

El archivo test/setup.ts configura mocks de 10 módulos nativos que no están disponibles en Node.js:

Cobertura por Area

Calidad del Código

Scripts de Desarrollo

# Iniciar servidor de desarrollo
npm start

# Iniciar con target específico
npm run ios         # Simulador iOS
npm run android     # Emulador Android

# Tests
npm run test        # Jest watch mode
npm run test:run    # Jest single run
npm run test:cov    # Jest con reporte de coverage

# Lint y formateo
npm run lint        # ESLint
npm run format      # Prettier

Referencias

• Código fuente: nvito-client/
• API Client: src/api/client.ts
• Services: src/api/services/ (7 archivos)
• Query Hooks: src/hooks/queries/ (7 archivos)
• Query Keys: src/hooks/queries/keys.ts
• AuthContext: src/contexts/AuthContext.tsx + src/contexts/auth/
• ConnectivityContext: src/contexts/ConnectivityContext.tsx
• Validations: src/validations/ (3 schemas)
• Theme: src/theme/colors.ts
• Storage: src/storage/ (secure-store, offline-queue)
• Notifications: src/hooks/use-notifications.ts
• Shared Components: src/components/itinerary/ (timeline-item, location-card)
• Types: src/types/ (7 archivos)
• Tests: test/setup.ts + **/__tests__/ (29 suites)