App Movil (nvito-client)

Tabla de Contenidos

1. Estructura del Proyecto
2. Navegacion y Rutas
3. Autenticacion Movil
4. Pantallas del Anfitrion (HOST)
5. Pantallas del Invitado (GUEST)
6. Arquitectura del API Client
7. Gestion de Estado
8. QR Scanner y Check-in
9. Media: Galeria y Audio Guestbook
10. Push Notifications
11. Deep Linking
12. Design System
13. Arquitectura SOLID
14. Validacion con Zod
15. Testing
16. Calidad del Codigo

Estructura del Proyecto

nvito-client es una aplicacion movil 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 dia del evento.

Stack Tecnologico

Configuracion de Plataforma

Estructura de Directorios

nvito-client/
├── app/                              # Expo Router (file-based routing)
│   ├── _layout.tsx                   # Root layout (QueryClient + AuthProvider)
│   ├── index.tsx                     # Redirect segun auth state
│   ├── +not-found.tsx                # Pantalla 404
│   ├── (auth)/                       # Grupo de autenticacion
│   │   ├── _layout.tsx               # Stack navigation
│   │   ├── login.tsx                 # Login anfitrion: codigo + PIN
│   │   └── join.tsx                  # Acceso invitado: deep link / QR
│   └── (app)/                        # Grupo principal (auth guard)
│       ├── _layout.tsx               # Guard + push token registration
│       ├── (host)/                   # Screens del anfitrion
│       │   ├── _layout.tsx           # Bottom Tab Navigation (5 tabs)
│       │   ├── dashboard.tsx         # Orquestador (~120 LOC)
│       │   │   ├── stat-card.tsx     # Card de estadistica individual
│       │   │   ├── countdown-card.tsx # Countdown al evento
│       │   │   ├── rsvp-breakdown-card.tsx # Desglose RSVP
│       │   │   └── recent-activity-card.tsx # Feed de actividad
│       │   ├── guests.tsx            # Orquestador (~150 LOC)
│       │   │   ├── guest-card.tsx    # Card de invitado (pressable)
│       │   │   ├── guest-detail-sheet.tsx  # Bottom sheet detalle completo
│       │   │   ├── stats-bar.tsx     # Barra de estadisticas
│       │   │   └── guest-filters.tsx # Filtros de status
│       │   ├── scanner.tsx           # Orquestador (~80 LOC)
│       │   │   ├── check-in-result-modal.tsx
│       │   │   ├── partial-check-in-modal.tsx
│       │   │   ├── manual-check-in-sheet.tsx  # Check-in manual por nombre
│       │   │   ├── stats-header.tsx
│       │   │   ├── recent-check-ins-list.tsx
│       │   │   ├── permission-screen.tsx
│       │   │   └── hooks/
│       │   │       ├── use-scanner.ts
│       │   │       └── use-manual-search.ts   # Busqueda + check-in manual
│       │   ├── tables.tsx            # Mesas (vista lista + plano)
│       │   ├── more.tsx              # Menu: memorias, itinerario, regalos, logout
│       │   ├── memorias.tsx          # Orquestador: Fotos | Audios | Mensajes
│       │   │   ├── segmented-control.tsx    # Selector 3 segmentos con badges
│       │   │   ├── memorias-gallery.tsx     # Grid de fotos + viewer
│       │   │   ├── memorias-audios.tsx      # Lista + filtros + player
│       │   │   ├── memorias-messages.tsx    # Lista + filtros
│       │   │   ├── photo-thumbnail.tsx      # Thumbnail reutilizable
│       │   │   ├── photo-viewer.tsx         # Modal full-screen
│       │   │   └── message-card.tsx         # Card de mensaje
│       │   ├── itinerary.tsx         # Itinerario HOST (shared components)
│       │   ├── gift-registry.tsx     # Mesa de regalos read-only
│       │   │   ├── cash-fund-progress.tsx   # Barra de progreso (centavos→pesos)
│       │   │   └── registry-item-card.tsx   # Card de tienda con link externo
│       │   ├── gallery.tsx           # Galeria de fotos (hidden tab)
│       │   ├── audio-guestbook.tsx   # Orquestador (~117 LOC)
│       │   │   ├── audio-item.tsx    # Item de mensaje de audio
│       │   │   ├── filter-tabs.tsx   # Tabs de filtro
│       │   │   └── hooks/use-audio-player.ts
│       │   └── messages.tsx          # Mensajes de texto (hidden tab)
│       └── (guest)/                  # Screens del invitado
│           ├── _layout.tsx           # Bottom Tab Navigation (4 tabs)
│           ├── home.tsx              # QR pass + countdown + info
│           ├── itinerary.tsx         # Programa + ubicaciones
│           ├── gallery.tsx           # Orquestador (~120 LOC)
│           │   ├── photo-thumbnail.tsx
│           │   ├── photo-viewer.tsx
│           │   └── hooks/use-photo-upload.ts
│           └── interact.tsx          # Audio, mensajes, regalos
├── src/
│   ├── api/                          # Capa de comunicacion HTTP
│   │   ├── client.ts                 # Fetch wrapper con interceptores
│   │   ├── errors.ts                 # ApiError class
│   │   ├── __tests__/               # Tests de API client
│   │   │   └── errors.test.ts
│   │   └── services/                 # Servicios por dominio (6 archivos)
│   │       ├── auth.service.ts       # Login, refresh, push token
│   │       ├── events.service.ts     # Datos del evento, stats
│   │       ├── guests.service.ts     # Invitados, check-in, QR
│   │       ├── media.service.ts      # Galeria, audio, mensajes
│   │       ├── payments.service.ts   # Cash fund (Stripe)
│   │       ├── sharing.service.ts    # Compartir evento
│   │       └── __tests__/            # Tests de servicios (6 archivos)
│   ├── hooks/                        # Custom hooks
│   │   ├── queries/                  # React Query hooks (7 archivos)
│   │   │   ├── keys.ts              # Query Key Factory
│   │   │   ├── use-event.ts         # Datos del evento
│   │   │   ├── use-event-stats.ts   # Estadisticas en vivo
│   │   │   ├── use-guests.ts        # Lista de invitados
│   │   │   ├── use-media.ts         # Galeria, audio, mensajes
│   │   │   ├── use-payments.ts      # Pagos cash fund
│   │   │   ├── use-sharing.ts       # Compartir evento
│   │   │   └── __tests__/           # Tests de hooks (6 archivos)
│   │   ├── use-notifications.ts     # Push notifications
│   │   └── use-responsive.ts        # Responsive / tablet detection
│   ├── contexts/
│   │   ├── AuthContext.tsx           # Provider limpio (~95 LOC)
│   │   ├── ConnectivityContext.tsx   # Monitor de conectividad
│   │   ├── auth/                    # Descomposicion SOLID del auth
│   │   │   ├── auth-reducer.ts      # AuthState, AuthAction, reducer
│   │   │   ├── auth-storage.ts      # Persistencia en SecureStore
│   │   │   └── use-session-restore.ts # Restauracion + auto-refresh
│   │   └── __tests__/              # Tests de contextos (4 archivos)
│   ├── storage/
│   │   ├── secure-store.ts          # Wrapper de expo-secure-store
│   │   ├── offline-queue.ts         # Cola offline (AsyncStorage)
│   │   └── __tests__/              # Tests de storage (2 archivos)
│   ├── validations/                  # Zod schemas para API responses
│   │   ├── auth.ts                  # loginResponseSchema, refreshResponseSchema
│   │   ├── event.ts                 # eventDetailSchema, eventStatsSchema
│   │   ├── guest.ts                 # checkInResultSchema, guestQrPassSchema
│   │   └── __tests__/              # Tests de validacion (3 archivos, 39 tests)
│   ├── theme/                        # Design system centralizado
│   │   ├── colors.ts                # Fuente unica de verdad de colores
│   │   └── index.ts                 # Barrel export
│   ├── types/                        # TypeScript types
│   │   ├── api.types.ts             # Tipos genericos de API
│   │   ├── auth.types.ts            # LoginResponse, MobileRole
│   │   ├── event.types.ts           # Event, EventStats
│   │   ├── guest.types.ts           # Guest, CheckInResult
│   │   ├── media.types.ts           # GalleryPhoto, AudioMessage
│   │   └── payments.types.ts        # CashFundIntentResponse
│   ├── utils/
│   │   ├── constants.ts             # Constantes (timeouts, tamanos)
│   │   ├── date.ts                  # Formateo de fechas
│   │   ├── format.ts                # Formateo general
│   │   └── __tests__/              # Tests de utils (2 archivos)
│   ├── config/
│   │   ├── env.ts                   # Variables de entorno
│   │   └── query-persister.ts       # Persistencia de React Query
│   └── components/
│       ├── ShareCardPreview.tsx      # Preview de card para compartir
│       └── itinerary/               # Componentes compartidos HOST/GUEST
│           ├── timeline-item.tsx     # Item de timeline con helpers
│           └── location-card.tsx     # Card de ubicacion con link a mapas
├── test/
│   └── setup.ts                      # Mocks globales (10 modulos nativos)
├── assets/                           # Iconos, splash, fuentes
├── jest.config.js                    # Configuracion Jest + jest-expo
├── app.json                          # Configuracion Expo
├── tailwind.config.js                # NativeWind + colores de theme/colors
├── babel.config.js                   # Babel preset
├── metro.config.js                   # Metro bundler
└── tsconfig.json                     # TypeScript (strict mode)

Navegacion y Rutas

La app usa Expo Router v6 con navegacion file-based. La estructura de navegacion se adapta segun el rol del usuario autenticado (HOST o GUEST).

Diagrama de Navegacion

Descripcion de Rutas

Tabs del Anfitrion

Tabs del Invitado

Autenticacion Movil

La app usa un sistema de autenticacion 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 Autenticacion del Anfitrion

Flujo de Autenticacion del Invitado

Almacenamiento de Sesion

Auto-refresh de Tokens

El AuthContext programa automaticamente la renovacion 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 rotacion 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 Anfitrion (HOST)

Dashboard

Pantalla principal del anfitrion con estadisticas 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 busqueda 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

Boton de busqueda 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 distribucion y asignacion de mesas del evento. La gestion (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 Galeria, Audio Guestbook y Mensajes en una sola pantalla con segmented control. Accesible desde el menu "Mas", 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 identico al del invitado, accesible desde el menu "Mas". 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 ubicacion).

Mesa de Regalos (HOST)

Vista read-only del estado de la mesa de regalos del evento. Accesible desde el menu "Mas". No incluye widget de Stripe ni boton de contribucion (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 informacion enriquecida.

Interactuar

Pantalla con secciones condicionales (service gating) para que el invitado interactue con el evento.

Hospedaje

Pantalla accesible desde "Mas" con toda la informacion de hospedaje del evento.

Mas

Menu con opciones condicionales segun servicios habilitados.

Service Gating

Las secciones y pantallas del invitado se muestran condicionalmente segun los servicios habilitados para el evento (useEventServices()). Si los servicios aun no se han cargado, se muestran todas las secciones como fallback.

Arquitectura del API Client

El sistema de comunicacion con el backend sigue una arquitectura en capas, similar a nvito-admin pero adaptada para autenticacion movil.

API Client (client.ts)

Fetch wrapper que encapsula todas las operaciones HTTP:

• Metodos: 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 automaticamente
• Auto-refresh: Si recibe 401, intenta renovar el JWT con el refresh token
• Error handling: Clase ApiError con statusCode y message

Services (6 archivos)

Prefijo de Endpoints Moviles

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

Gestion de Estado

React Query 5

La app usa TanStack React Query como unico sistema de gestion 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.audioMessages(eventId)    // ['media', eventId, 'audio']
queryKeys.media.messages(eventId)         // ['media', eventId, 'messages']

Hooks de React Query

AuthContext (Descomposicion SOLID)

El contexto de autenticacion fue descompuesto siguiendo SRP en 4 archivos con responsabilidad unica:

El contexto gestiona el estado de sesion con un useReducer:

Acciones del reducer:

• RESTORE_SESSION — Restaurar sesion desde SecureStore al montar
• LOGIN — Login exitoso (host o guest)
• LOGOUT — Cerrar sesion 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 unico 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 esta ya registrado
4. Si el invitado tiene groupSize > 1, se muestra un modal para seleccionar cuantos asisten

Check-in Parcial (Grupos)

Cuando un invitado tiene acompanantes, el scanner muestra:

• Nombre del invitado y total del grupo
• Stepper numerico para seleccionar asistentes
• Rango: 1 hasta groupSize
• Soporte para re-escaneo (agregar mas personas despues)

Media: Galeria y Audio Guestbook

Upload de Fotos

Grabacion de Audio

Limites de Media

Push Notifications

Registro de Push Token

Configuracion 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

Configuracion

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 Unica de Verdad: src/theme/colors.ts

Todos los colores de la aplicacion estan centralizados en un unico archivo src/theme/colors.ts exportado como as const para type safety. El archivo tailwind.config.js importa estos colores directamente, eliminando la duplicacion.

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

Paleta de Colores

Integracion 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">Descripcion</Text>
</View>

Tipografia

Responsive / Tablet

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

Iconografia

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) sistematicamente. Las pantallas grandes fueron descompuestas en orquestadores livianos + sub-componentes + hooks custom.

Descomposicion de Pantallas

Reduccion total: 70% menos lineas en archivos orquestadores, distribuidas en componentes enfocados y reutilizables.

Descomposicion del AuthContext

Validacion con Zod

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

Schemas Disponibles

Cada schema tiene tests que verifican datos validos, campos faltantes y tipos incorrectos.

Testing

El proyecto cuenta con 28 suites de prueba y 216 tests individuales, todos con 100% de tasa de exito.

Framework

Mocks Globales

El archivo test/setup.ts configura mocks de 10 modulos nativos que no estan disponibles en Node.js:

Cobertura por Area

Calidad del Codigo

Scripts de Desarrollo

# Iniciar servidor de desarrollo
npm start

# Iniciar con target especifico
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

• Codigo fuente: nvito-client/
• API Client: src/api/client.ts
• Services: src/api/services/ (6 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__/ (28 suites)