Arquitectura del Sistema

1. Arquitectura de Alto Nivel (C4 Context)

La plataforma Nvito está compuestá por cuatro aplicaciones principales que trabajan en conjunto para ofrecer la experiencia completa de gestión de eventos sociales. Cada aplicación tiene un proposito específico y se comúnica con servicios externos especializados.

1.1 Aplicaciones del Sistema

1.2 Servicios Externos

1.3 Actores del Sistema

1.4 Diagrama C4 de Contexto

2. Arquitectura de Contenedores (C4 Container)

Cada aplicación tiene una estructura interna compuestá por capas y componentes especializados. A continuacion se detalla la composición interna de cada contenedor.

2.1 nvito-api (NestJS) - Componentes Internos

El backend está construido con NestJS y sigue una arquitectura modular por capas:

Modulos registrados en AppModule (39 de dominio + 5 de infraestructura = 44 total):

• Core: AuthModule, OrganizationsModule, UsersModule, RolesModule, AdminModule, PackagesModule, HealthModule
• Eventos: EventsModule, EventTypesModule, EventServicesModule, ContractsModule
• Invitaciones: InvitationsModule, TemplatesModule, HtmlGenerationModule
• Invitados: GuestsModule, GuestGroupsModule, RsvpModule, TablesModule
• Clientes: ClientsModule
• Features: LocationsModule, ItineraryModule, QRPassesModule, GiftRegistryModule, AccommodationModule, BackgroundMusicModule, MusicModule
• Media: MediaModule, StorageModule, CustomDomainModule
• IA: AIGenerationModule
• Comunicaciones: NotificationsModule, NotificationChannelsModule, CommunicationsModule, QueueModule, SchedulerModule
• Pagos: PaymentsModule
• Movil: MobileModule, MobileAuthModule
• Analitica: AnalyticsModule
• Infraestructura: PrismaModule, CommonModule, ActivityLogModule, PermissionsModule, ConfigModule

2.2 nvito-admin (Next.js 16) - Componentes Internos

2.3 nvito-client (React Native / Expo) - Componentes Internos

2.4 nvito-invitations (Next.js 16) - Componentes Internos

Aplicación mínimalista con solo 7 dependencias de producción. Agnostica al origen: renderiza invitaciones de forma identica sin importar si fueron creadas con el motor de templates de Nvito (INTERNAL) o subidas como HTML externo (EXTERNAL).

2.5 Diagrama C4 de Contenedores

3. Flujo de Request HTTP

Cada peticion HTTP que llega a nvito-api atraviesa una cadena de middleware, guards e interceptors antes de llegar al controlador. El orden de ejecución es critico para la seguridad y el aislamiento de datos.

3.1 Cadena de Ejecución

El flujo completo de un request autenticado es el siguiente:

1. HTTP Request - La peticion llega al servidor NestJS (puerto configurable, default 3000)
2. Helmet + CORS + Compression - Middleware de seguridad y rendimiento configurados en main.ts
3. ValidationPipe - Validación global de DTOs con whitelist y forbidNonWhitelisted
4. ClerkAuthGuard - Verifica el JWT de Clerk, busca el usuario en la BD, resuelve roles desde user_roles, valida que el usuario este activo y no eliminado
5. UserThrottlerGuard - Rate limiting por usuario autenticado (100 req/min) o por IP para rutas públicas, almacenado en Redis
6. TenantMiddleware - Extrae el organizationId del usuario autenticado y ejecuta SET LOCAL app.current_tenant_id en PostgreSQL para activar RLS
7. RoleGuard - Verifica que el rol del usuario (owner, admin, member, super_admin) cumple con el mínimo requerido por la ruta
8. PermissionsGuard - Valida permisos granulares definidos con @RequirePermission('resource:action:scope')
9. Controller - Recibe la peticion validada, extrae parametros y delega al servicio
10. Service - Ejecuta la lógica de negocio, validaciones de dominio y operaciones
11. Prisma - Ejecuta queries contra PostgreSQL con RLS activo (filtrado automático por tenant)
12. AuditInterceptor - Tras una respuesta exitosa en rutas criticas (POST/PATCH/PUT/DELETE), registra la acción en audit_log de forma asincrona
13. Response - Se envia la respuesta al cliente con compresion gzip

3.2 Diagrama de Secuencia del Request

3.3 Notas sobre el Flujo

• Orden de guards: El orden en AppModule importa. ClerkAuthGuard va primero para que req.user este disponible para UserThrottlerGuard
• Rutas excluidas de TenantMiddleware: webhooks/* y health no pasan por el middleware de tenant
• Auditoria asincrona: El AuditInterceptor no bloquea la respuesta HTTP; el registro en audit_log se ejecuta en background
• Rate limiting con Redis: El RedisThrottlerStorage usa Redis compartido para funcionar correctamente con múltiples instancias del API

4. Multi-Tenancy

Nvito implementa multi-tenancy a nivel de base de datos utilizando PostgreSQL Row Level Security (RLS). Cada organización es un tenant aislado, y el mecanismo garantiza que un tenant nunca pueda acceder a los datos de otro.

4.1 Concepto General

4.2 Como Funciona el TenantMiddleware

El TenantMiddleware en /nvito-api/src/database/tenant.middleware.ts es el componente central del sistema multi-tenant:

// Extracto simplificado del TenantMiddleware
async use(req: Request, res: Response, next: NextFunction) {
  const user = req.user as AuthenticatedUser;

  if (user && user.organizationId) {
    // SECURITY: Usar $executeRaw con tagged template para prevenir SQL injection
    await this.prisma
      .$executeRaw`SELECT set_config('app.current_tenant_id', ${user.organizationId}, true)`;
  }

  next();
}

Puntos clave:

• Usa set_config con el tercer parametro true para que sea local a la transacción (SET LOCAL)
• El organizationId ya fue resuelto y validado por ClerkAuthGuard desde la tabla user_roles
• Previene SQL injection usando tagged templates de Prisma ($executeRaw)
• Solo se aplica si el usuario está autenticado y tiene una organización asignada
• Las rutas de webhooks y health estan excluidas

4.3 Politica RLS en PostgreSQL

-- Ejemplo de politica RLS aplicada a la tabla events
CREATE POLICY tenant_isolation_policy ON events
  USING (organization_id = current_setting('app.current_tenant_id')::uuid);

-- Cuando el usuario ejecuta:
SELECT * FROM events WHERE status = 'published';

-- PostgreSQL realmente ejecuta (RLS transparente):
SELECT * FROM events
WHERE status = 'published'
AND organization_id = 'uuid-de-la-org';  -- Anadido automáticamente por RLS

4.4 Diagrama de Secuencia Multi-Tenancy

4.5 Garantias de Aislamiento

5. Comunicación entre Servicios

La comunicación entre las cuatro aplicaciones y los servicios externos sigue patrones específicos según el tipo de interacción.

5.1 Admin a API (Sincrono)

El flujo tipico es:

1. nvito-admin obtiene el JWT del usuario autenticado via Clerk Provider
2. El API Client adjunta el token como Authorization: Bearer <jwt>
3. nvito-api valida el token, resuelve el usuario y aplica el contexto de tenant
4. La respuesta se cachea en React Query con keys basadas en el recurso

5.2 Invitations a API (Sincrono - Parcialmente Publico)

5.3 App Movil a API (Sincrono - JWT Movil)

El flujo tipico es:

1. El usuario se autentica con código de evento + PIN (host) o access token (guest)
2. nvito-api genera un JWT de 15 min + refresh token de 30 dias
3. Los tokens se almacenan en expo-secure-store (almacenamiento encriptado nativo)
4. El API Client inyecta el Bearer token en cada request
5. Si recibe 401, intenta renovar el JWT con el refresh token automáticamente

5.4 API a Invitations (Webhook ISR)

Cuando un anfitrion modifica una invitación en nvito-admin, el API notifica a nvito-invitations para que regenere la página estática:

5.5 API a Queue (Asincrono)

Las tareas que no requieren respuesta inmediata se procesan a traves de colas BullMQ:

5.6 Webhooks Entrantes

Estás rutas estan excluidas del TenantMiddleware y utilizan verificacion de firma propia del servicio externo (Svix para Clerk, Twilio signature, Stripe signature).

5.7 Invitations a CDN

Las invitaciones públicas se sirven desde el edge de la CDN:

6. Patrones Arquitectonicos

6.1 Multi-Repo

Nvito utiliza una estrategia de múltiples repositorios independientes:

Ventajas de este enfoque:

• CI/CD independiente: Cada aplicación tiene su propio pipeline de build, test y deploy
• Versiónado independiente: Las versiones de cada aplicación avanzan a su propio ritmo
• Equipos autonomos: Diferentes desarrolladores pueden trabajar en cada repositorio sin conflictos
• Deployment aislado: Un deploy de nvito-admin no afecta a nvito-api ni a nvito-invitations
• Tecnologias especializadas: Cada repo puede tener sus propias dependencias y configuraciones

6.2 Arquitectura por Capas (Layered Architecture)

El backend sigue una arquitectura estrictamente por capas con dependencias unidireccionales:

Controller --> Service --> Repository (Prisma)

Reglas:

• Los controllers nunca acceden directamente a Prisma
• Los services pueden inyectar otros services para orquestacion
• La capa de datos (Prisma) es la única que interactua con PostgreSQL

6.3 CQRS-Lite (Command Query Responsibility Segregation)

Nvito aplica una versión simplificada de CQRS donde las operaciones se separan por semantica HTTP:

Diferencias con CQRS completo:

• No hay modelos de lectura y escritura separados
• No hay event store ni event sourcing
• La separacion es a nivel de convención HTTP, no de infraestructura
• El AuditInterceptor solo registra Commands (POST/PATCH/PUT/DELETE), no Queries (GET)

6.4 Event-Driven para Tareas Asincronas (BullMQ)

Las operaciones que no requieren respuesta inmediata se delegan a colas de trabajo:

Service --> QueueModule.add(jobName, payload) --> Redis (BullMQ) --> Worker/Processor

Casos de uso tipicos:

• Envio de email de confirmación tras RSVP
• Generación de HTML compilado de invitación
• Procesamiento de generación de contenido con IA
• Envio de recordatorios programados
• Procesamiento batch de metricas de analytics

6.5 ISR (Incremental Static Regeneration) para Paginas Publicas

Las invitaciones públicas usan ISR para combinar el rendimiento de páginas estáticas con la capacidad de actualizar contenido:

Beneficios:

• Tiempo de carga < 1 segundo (servido desde CDN edge)
• Core Web Vitals optimizados (LCP, FID, CLS)
• Costo de infraestructura bajo (no requiere servidor activo para cada request)
• Actualización en tiempo casi-real cuando el anfitrion modifica la invitación

6.6 Seguridad en Capas

La seguridad se implementa como múltiples capas que un request debe atravesar:

Referencias

• Modelo C4 de Arquitectura
• NestJS Documentation
• PostgreSQL Row Level Security
• Next.js ISR
• BullMQ Documentation
• Clerk Authentication