API Overview (nvito-api)

Documentacion tecnica del backend NestJS que expone la API REST de Nvito. Framework: NestJS 11 | ORM: Prisma | Auth: Clerk | Queue: Bull/Redis | Payments: Stripe

1. Estructura de Modulos

La API esta compuesta por 39 modulos de dominio organizados en 9 dominios funcionales, mas 6 modulos de infraestructura (45 modulos totales).

1.1 Dominios y Modulos

Dominio	Modulos	Descripcion
Core	`auth`, `organizations`, `users`, `roles`, `admin`, `packages`, `health`	Autenticacion, multitenancy, RBAC y administracion del sistema
Eventos	`events`, `event-types`, `event-services`, `contracts`, `clients`	Ciclo de vida de eventos, catalogo de tipos, servicios habilitados, contratos de venta y gestion de clientes
Invitaciones	`invitations`, `sections`, `templates`, `html-generation`	Creacion, edicion visual, plantillas artesanales y compilacion HTML
Invitados	`guests`, `guest-groups`, `rsvp`, `tables`	Gestion de invitados, grupos familiares, confirmaciones y asignacion de mesas
Features	`locations`, `itinerary`, `qr-passes`, `gift-registry`, `accommodation`, `background-music`, `music`	Funcionalidades opcionales habilitables por evento
Media	`media`, `storage`, `custom-domain`	Subida de archivos a R2, galeria, audio guestbook y dominios personalizados
IA	`ai-generation`	Generacion y modificacion de invitaciones con IA (OpenAI/Anthropic)
Comunicaciones	`notifications`, `notification-channels`, `communications`, `queue`, `scheduler`	Envio de emails/WhatsApp/push, colas Bull y tareas programadas
Pagos	`payments`	Integracion con Stripe: links de pago, webhooks, historial
Movil	`mobile`, `mobile-auth`	Endpoints dedicados para app movil, auth independiente de Clerk
Analitica	`analytics`	Tracking de vistas, RSVP analytics y metricas por evento

1.2 Modulos de Infraestructura

Modulo	Funcion
`PrismaModule`	Conexion a PostgreSQL con soporte multi-tenant
`CommonModule`	Servicios compartidos: EncryptionService, CacheService, OrganizationResolverService, RedisThrottlerStorage
`ActivityLogModule`	Sistema de auditoria global (tabla `audit_log`)
`PermissionsModule`	Sistema RBAC con permisos granulares
`MetricsModule`	Metricas de rendimiento y uso del sistema
`ConfigModule`	Configuracion centralizada con validacion Zod
`WinstonModule`	Logging con rotacion diaria de archivos
`ThrottlerModule`	Rate limiting respaldado por Redis

1.3 Diagrama de Modulos

2. Tabla de Endpoints

Todos los endpoints tienen el prefijo global /v1. Las rutas marcadas con "Public" no requieren autenticacion.

Health

/v1

Public

Auth

Auth — Webhooks

/v1

Public

Auth — Validacion de Invitaciones

/v1

Public

Organizations

Organizations — Admin Panel

/v1

Clerk

Organizations — Tenant

/v1

Clerk

Users

/v1

Clerk

Roles

Roles — Asignacion y Gestion

/v1

Clerk

Roles — Colaboradores de Evento

/v1

Clerk

Roles — Invitaciones de Colaborador

/v1

Clerk

Admin

Admin — System Health

/v1

Clerk

Admin — Usuarios

/v1

Clerk

Admin — Invitaciones (Pre-registros)

/v1

Clerk

Admin — Roles y Estadisticas

/v1

Clerk

Packages

Packages — Paquetes de Servicios

/v1

Clerk

Eventos

Clerk

Public

Clerk

Tipos de Evento

Clerk

Servicios de Evento

Clerk

Public

Contratos

Clerk

Metricas de Ventas

Clerk

Clientes

Clerk

Invitaciones

Clerk

Public

Clerk

Public

Clerk

Templates

Clerk

Guests

/v1

Clerk

Guest Groups

/v1

Clerk

RSVP

/v1

Public

Clerk

Tables

/v1

Clerk

Locations

/v1

Clerk

Itinerary

/v1

Clerk

QR Passes

/v1

Clerk

Gift Registry

/v1

Clerk

Accommodation

/v1

Clerk

Background Music

/v1

Clerk

Music

/v1

Clerk

Media

/v1

Clerk

Custom Domain

/v1

Clerk

AI Generation

/v1

Clerk

Notificaciones

/v1

Clerk

Comunicaciones

/v1

Clerk

Comunicaciones - Webhooks

/v1

Public

Plantillas de Comunicacion

/v1

Clerk

Workflows de Comunicacion

/v1

Clerk

Gestion de Colas

/v1

Clerk

Pagos

Pagos - Admin

/v1

Clerk

Pagos - Mobile (Cash Fund)

/v1

Public

Pagos - Publico

/v1

Public

Pagos - Webhooks

/v1

Public

Autenticacion Movil

/v1

Public

Mobile JWT

Codigos de Acceso de Eventos

/v1

Clerk

Mobile

Mobile - Eventos

/v1

Mobile JWT

Mobile - Check-in

/v1

Mobile JWT

Mobile - Invitados

/v1

Mobile JWT

Mobile - Media

/v1

Mobile JWT

Mobile - Sharing

/v1

Mobile JWT

Mobile - Mesas

/v1

Mobile JWT

Analiticas

/v1

Public

Clerk

3. Configuracion Global

3.1 ValidationPipe

Configurado globalmente en main.ts para validar todos los DTOs entrantes:

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,              // Elimina propiedades no declaradas en el DTO
    forbidNonWhitelisted: true,   // Rechaza requests con propiedades no declaradas
    transform: true,              // Transforma payloads al tipo del DTO
    transformOptions: {
      enableImplicitConversion: true,  // Convierte tipos automaticamente
    },
  }),
);

3.2 GlobalExceptionFilter

Filtro de excepciones que sanitiza errores en produccion para evitar exponer detalles internos del sistema al cliente.

3.3 AuditInterceptor

Interceptor global que registra automaticamente acciones criticas de modificacion:

Metodos auditados: POST, PATCH, PUT, DELETE (no GET)
Paths criticos: /users, /events, /guests, /invitations, /organizations, /templates, /rsvp, /locations, /itinerary, /tables
Solo audita: Requests autenticados (con usuario)
No bloquea: La auditoria es asincrona, no afecta el tiempo de respuesta
Registra: userId, organizationId, action (create/update/delete), resource, resourceId, IP, userAgent, metadata (path, method, body sanitizado)
Para Super Admin: Resuelve organizationId desde el recurso o evento padre via consulta a BD

3.4 Prefijo de API

Prefijo global: /v1
Ejemplo: http://localhost:3000/v1/events

3.5 Swagger

Disponible solo en entornos no-produccion:

URL: /api/docs

Incluye documentacion interactiva con esquemas de request/response, autenticacion Bearer y tags por modulo.

3.6 Seguridad adicional en main.ts

Middleware	Funcion
Helmet	Headers de seguridad (CSP, HSTS, X-Frame-Options, noSniff)
CORS	Origen validado contra whitelist; wildcard prohibido en produccion
Compresion gzip	Comprime responses > 1KB (reduce bandwidth 70-90%)
Body limits	Maximo 20MB para JSON y URL-encoded (para uploads)
Headers adicionales	X-Permitted-Cross-Domain-Policies, Referrer-Policy, Permissions-Policy

3.7 Global Guards (orden de ejecucion)

ClerkAuthGuard - Autenticacion JWT (valida token de Clerk, resuelve usuario en BD)
UserThrottlerGuard - Rate limiting (100 req/min por usuario o IP)
RoleGuard - Autorizacion basada en roles RBAC

4. Patron de un Modulo

Todos los modulos siguen el mismo patron estandar de NestJS:

4.1 Estructura de archivos

src/modules/events/
  events.module.ts          # Registra controller, services e imports
  events.controller.ts      # Recibe HTTP, valida DTO, delega al service
  events.service.ts         # Logica de negocio principal (facade)
  services/                 # Sub-servicios con responsabilidad unica (SRP)
    event-query.service.ts      # Consultas de lectura
    event-mutation.service.ts   # Operaciones de escritura
    event-capacity.service.ts   # Calculo de capacidad
    event-admin-query.service.ts # Consultas admin
  dto/
    create-event.dto.ts     # Validacion de entrada con class-validator
    update-event.dto.ts     # DTO parcial (PartialType)
    query-events.dto.ts     # Parametros de paginacion y filtros

4.1.1 Patron Sub-Services (SRP)

Los modulos complejos extraen logica en sub-servicios dentro de un directorio services/. El servicio principal actua como facade, delegando a sub-servicios especializados:

Modulo	Sub-servicios	Responsabilidad
`events`	`event-query`, `event-mutation`, `event-capacity`, `event-admin-query`	Separacion lectura/escritura/admin
`organizations`	`organization-admin`	Metodos Super Admin separados del tenant
`analytics`	`event-analytics`, `invitation-analytics`, `report-data`, `pdf-builder`	Analiticas por dominio y generacion de reportes
`invitations`	`invitation-lifecycle`, `invitation-section`, `version-manager`, `approval-workflow`, `preview-token`, `png-export`	Ciclo de vida, secciones, versiones, aprobacion
`ai-generation`	`prompt-builder`, `schema-section-builder`, `vision-provider`, `design-extraction`, `ai-modification`, `generation-cost`, `enrich-prompt`, `ai-provider-orchestrator`, `invitation-schema-builder`	Pipeline de generacion IA
`communications`	`campaign-query`, `invitation-dispatcher`, `message-dispatcher`, `recipient-filter`, `reminder-message-dispatcher`, `recipient-estimator`, `spam-prevention`, `smart-routing`, `message-preview`, `communication-template`	Envio por tipo, filtrado, templates, preview, spam prevention y routing
`payments`	`payment-link`, `stripe-webhook`	Links de pago y webhooks Stripe
`tables`	`table-assignment`, `table-stats`	Asignacion y estadisticas
`mobile`	`mobile-events`, `mobile-guests`, `mobile-check-in`, `mobile-media`, `mobile-sharing`, `card-generator`	Endpoints movil por dominio
`admin`	`admin-statistics`, `admin-user`, `admin-invitation`	Panel de administracion
`html-generation`	`template-compiler`, `schema-compiler`, `template-builder`, `html-optimizer`, `artisan-template-registry`	Pipeline de compilacion HTML
`qr-passes`	`qr-generation`, `qr-check-in`	Generacion y validacion QR
`guests`	`guest-stats`	Estadisticas de invitados
`contracts`	`contract-analytics`	Analiticas de contratos
`media`	`media-analytics`	Analiticas de media
`event-services`	`event-service-toggle`	Toggle de servicios

Total: 61 sub-servicios distribuidos en 17 modulos, lo que mantiene cada archivo enfocado en una sola responsabilidad.

4.2 Module

@Module({
  imports: [PrismaModule, CommonModule],
  controllers: [EventsController],
  providers: [EventsService],
  exports: [EventsService],  // Exporta el service para uso en otros modulos
})
export class EventsModule {}

4.3 Controller

@ApiTags('events')
@ApiBearerAuth()
@Controller('events')
@UseGuards(ClerkAuthGuard)
export class EventsController {
  constructor(private readonly eventsService: EventsService) {}

  @Post()
  @UseGuards(PermissionsGuard)
  @RequirePermission(PERMISSIONS.EVENTS_CREATE_ORG)
  async create(
    @CurrentUser() user: AuthenticatedUser,
    @Body() createEventDto: CreateEventDto,
  ) {
    return this.eventsService.create(organizationId, user.userId, createEventDto);
  }
}

4.4 Service

@Injectable()
export class EventsService {
  constructor(private readonly prisma: PrismaService) {}

  async create(orgId: string, userId: string, dto: CreateEventDto) {
    return this.prisma.event.create({
      data: {
        ...dto,
        organizationId: orgId,
        createdBy: userId,
      },
    });
  }
}

4.5 DTO

export class CreateEventDto {
  @IsString()
  @IsNotEmpty()
  @MaxLength(200)
  name: string;

  @IsUUID()
  eventTypeId: string;

  @IsDateString()
  date: string;

  @IsOptional()
  @IsString()
  @MaxLength(2000)
  description?: string;
}

5. Rate Limiting

5.1 Configuracion

ThrottlerModule.forRootAsync({
  imports: [CommonModule],
  useFactory: (redisStorage: RedisThrottlerStorage) => ({
    throttlers: [{ ttl: 60000, limit: 100 }],  // 100 requests por minuto
    storage: redisStorage,                       // Respaldado por Redis
  }),
  inject: [RedisThrottlerStorage],
}),

5.2 UserThrottlerGuard

Limite global: 100 peticiones por minuto
Tracking: Por usuario autenticado (userId) o por IP (para endpoints publicos)
Storage: Redis (compatible con multiples instancias del servidor)
Excepciones: El endpoint /health usa @SkipThrottle() para bypasear el limite
Override por endpoint: El webhook de Clerk tiene limite personalizado de 50 req/min via @Throttle({ default: { limit: 50, ttl: 60000 } })

6. Validacion y Serializacion

6.1 class-validator (Validacion de entrada)

Todos los DTOs utilizan decoradores de class-validator para validar datos de entrada:

@IsString(), @IsNumber(), @IsUUID(), @IsEmail() - Validacion de tipos
@IsNotEmpty(), @IsOptional() - Campos requeridos vs opcionales
@MaxLength(), @MinLength(), @Min(), @Max() - Limites de longitud/valor
@IsDateString(), @IsEnum() - Formatos especificos
@ValidateNested() con @Type() - Objetos anidados

6.2 class-transformer (Serializacion)

Se usa class-transformer para transformar payloads entrantes:

enableImplicitConversion: true convierte strings a numeros, booleanos, etc.
@Type(() => Number) para transformar tipos en objetos anidados
@Exclude() para omitir campos sensibles en respuestas

6.3 Zod (Validacion de entorno)

Las variables de entorno se validan al arranque con un schema Zod en config/env.validation.ts:

const envSchema = z.object({
  DATABASE_URL: z.string().min(1, 'DATABASE_URL es requerida'),
  NODE_ENV: z.enum(['development', 'staging', 'production', 'test']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  CLERK_SECRET_KEY: z.string().min(1),
  CLERK_PUBLISHABLE_KEY: z.string().min(1),
  REDIS_URL: z.string().default('redis://localhost:6379'),
  // ... mas variables
});

Si alguna variable requerida falta o es invalida, la aplicacion no arranca y muestra un mensaje claro del error.

6.4 Convenciones de nomenclatura de DTOs

Patron	Uso	Ejemplo
`Create{Entity}Dto`	Creacion de recurso	`CreateEventDto`
`Update{Entity}Dto`	Actualizacion parcial (PartialType)	`UpdateEventDto`
`Query{Entity}Dto`	Parametros de lista/busqueda/paginacion	`QueryEventsDto`
`{Action}{Entity}Dto`	Acciones especificas	`AssignGuestDto`, `ToggleServiceDto`
`{Entity}ResponseDto`	Formato de respuesta	`GenerationResultDto`

Metricas del Proyecto

Metrica	Cantidad
Modulos totales	45 (39 de dominio + 6 de infraestructura)
Controladores	49
Servicios	136 (75 principales + 61 sub-servicios)
Endpoints HTTP	369
DTOs	100
Guards	11
Interceptors	3
Processors (Bull)	3 (email, whatsapp, push)
Filtros	1 (GlobalExceptionFilter)
Modelos Prisma	51
Enums Prisma	36
Tests	207 suites / 3311+ tests (100% green)
Cobertura servicios	116/116 (100%)
Cobertura controllers	48/48 (100%) -- excluye 2 controllers publicos sin logica testeable
Cobertura guards	11/11 (100%)

Metricas de nvito-admin (Frontend)

Para referencia cruzada, las metricas del panel de administracion:

Metrica	Cantidad
Test suites	133
Tests individuales	1,347 (100% green)
Framework de tests	Vitest 4.x + Testing Library
Server Actions	16 archivos (todos con Zod validation)
API Services	33 archivos con tests
React Query Hooks	35+ archivos con tests
Esquemas Zod	15 (todos con tests)
Componentes UI (shadcn)	41+
React Compiler	Habilitado
CSP Headers	Configurados
Accesibilidad	aria-sort, aria-label, keyboard nav

Archivos clave referenciados

Archivo	Ruta
App Module	`nvito-api/src/app.module.ts`
Bootstrap	`nvito-api/src/main.ts`
Audit Interceptor	`nvito-api/src/common/interceptors/audit.interceptor.ts`
Env Validation	`nvito-api/src/config/env.validation.ts`
Throttler Guard	`nvito-api/src/common/throttler/user-throttler.guard.ts`
Redis Storage	`nvito-api/src/common/throttler/redis-throttler.storage.ts`
Global Exception Filter	`nvito-api/src/common/filters/global-exception.filter.ts`