Arquitectura del Sistema

Informacion del Documento

Tabla de Contenidos

1. Arquitectura de Alto Nivel (C4 Context)
2. Arquitectura de Contenedores (C4 Container)
3. Flujo de Request HTTP
4. Multi-Tenancy
5. Comunicacion entre Servicios
6. Patrones Arquitectonicos

1. Arquitectura de Alto Nivel (C4 Context)

La plataforma Nvito esta compuesta por cuatro aplicaciones principales que trabajan en conjunto para ofrecer la experiencia completa de gestion de eventos sociales. Cada aplicacion tiene un proposito especifico y se comunica 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 aplicacion tiene una estructura interna compuesta por capas y componentes especializados. A continuacion se detalla la composicion interna de cada contenedor.

2.1 nvito-api (NestJS) - Componentes Internos

El backend esta 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

Aplicacion minimalista con solo 7 dependencias de produccion. 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 ejecucion es critico para la seguridad y el aislamiento de datos.

3.1 Cadena de Ejecucion

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 - Validacion 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 publicas, 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 minimo 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 logica de negocio, validaciones de dominio y operaciones
11. Prisma - Ejecuta queries contra PostgreSQL con RLS activo (filtrado automatico por tenant)
12. AuditInterceptor - Tras una respuesta exitosa en rutas criticas (POST/PATCH/PUT/DELETE), registra la accion 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 multiples instancias del API

4. Multi-Tenancy

Nvito implementa multi-tenancy a nivel de base de datos utilizando PostgreSQL Row Level Security (RLS). Cada organizacion 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 transaccion (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 esta autenticado y tiene una organizacion 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 automaticamente por RLS

4.4 Diagrama de Secuencia Multi-Tenancy

4.5 Garantias de Aislamiento

5. Comunicacion entre Servicios

La comunicacion entre las cuatro aplicaciones y los servicios externos sigue patrones especificos segun el tipo de interaccion.

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 codigo 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 automaticamente

5.4 API a Invitations (Webhook ISR)

Cuando un anfitrion modifica una invitacion en nvito-admin, el API notifica a nvito-invitations para que regenere la pagina estatica:

5.5 API a Queue (Asincrono)

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

5.6 Webhooks Entrantes

Estas 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 publicas se sirven desde el edge de la CDN:

6. Patrones Arquitectonicos

6.1 Multi-Repo

Nvito utiliza una estrategia de multiples repositorios independientes:

Ventajas de este enfoque:

• CI/CD independiente: Cada aplicacion tiene su propio pipeline de build, test y deploy
• Versionado independiente: Las versiones de cada aplicacion 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 unica que interactua con PostgreSQL

6.3 CQRS-Lite (Command Query Responsibility Segregation)

Nvito aplica una version 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 convencion 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 confirmacion tras RSVP
• Generacion de HTML compilado de invitacion
• Procesamiento de generacion 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 publicas usan ISR para combinar el rendimiento de paginas estaticas 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)
• Actualizacion en tiempo casi-real cuando el anfitrion modifica la invitacion

6.6 Seguridad en Capas

La seguridad se implementa como multiples capas que un request debe atravesar:

Referencias

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