Flujo de Media y Galeria

Upload seguro con presigned URLs, procesamiento de imagenes con sharp, almacenamiento en S3/R2, y distribucion global via CDN. Incluye galeria publica en invitaciones y audio guestbook para mensajes de voz.

Tabla de Contenidos

1. Vision General
2. Presigned URL Flow
3. Confirmacion y Validacion
4. Procesamiento de Imagenes
5. Categorias de Media
6. Limites por Plan
7. Infraestructura de Storage
8. Galeria Publica en Invitaciones
9. Audio Guestbook
10. Diagrama del Flujo de Upload
11. Archivos Clave

1. Vision General

El sistema de media de Nvito maneja todos los archivos subidos por usuarios: fotos de la galeria del evento, imagenes hero de invitaciones, logos de organizacion, fondos de seccion, audio del guestbook, y videos del evento.

El diseno sigue el principio de upload directo a S3: el cliente nunca envia el archivo al servidor de Nvito. En su lugar, solicita una URL pre-firmada (presigned URL), sube el archivo directamente al bucket de S3, y luego confirma la operacion. Esto elimina la carga de procesamiento del API y permite manejar archivos grandes sin timeout.

Numeros clave

2. Presigned URL Flow

El upload comienza cuando el cliente solicita permiso para subir un archivo. El servidor no recibe el archivo, solo genera una URL temporal con permisos de escritura.

Paso 1: Solicitar URL

El cliente envia POST /v1/media/get-upload-url con:

Paso 2: Validacion previa

Antes de generar la URL, MediaService valida:

1. Permisos: El usuario tiene acceso al evento (via OrganizationResolverService)
2. MIME type: Esta en la whitelist de tipos permitidos para la categoria
3. Tamano: No excede el limite del plan de la organizacion
4. Cuota: La organizacion no ha excedido su cuota total de almacenamiento

Paso 3: Generar presigned URL

StorageService.generatePresignedUrl() genera una URL con:

• Metodo: PUT
• Bucket: Segun la categoria (ver seccion 7)
• Key: {organizationId}/{eventId}/{category}/{uuid}.{ext}
• Expiracion: 15 minutos
• Condiciones: Content-Type debe coincidir con el declarado, Content-Length dentro del rango

Paso 4: Upload directo

El cliente ejecuta un PUT directo contra la presigned URL de S3 con el archivo como body. Este request no pasa por nvito-api.

Respuesta al cliente

3. Confirmacion y Validacion

Despues de subir el archivo a S3, el cliente debe confirmar la operacion. Esta confirmacion dispara la validacion real del archivo.

Endpoint de confirmacion

POST /v1/media/confirm-upload con { mediaId }

Pipeline de validacion

1. Verificar existencia: Confirmar que el archivo existe en S3 con el key esperado
2. Verificar tamano real: Comparar Content-Length del objeto en S3 con el tamano declarado
3. Magic bytes check: Leer los primeros bytes del archivo y verificar que coincidan con el MIME type declarado. Esto previene ataques donde se renombra un ejecutable como .jpg

4. Actualizar registro: Marcar el Media como CONFIRMED, almacenar metadata (tamano real, dimensiones si es imagen)
5. Disparar procesamiento: Encolar job de procesamiento en Bull queue

Registro Media

4. Procesamiento de Imagenes

Las imagenes confirmadas pasan por un pipeline de procesamiento usando la libreria sharp.

Pipeline

1. Metadata extraction: Leer dimensiones (width, height), formato, espacio de color, y datos EXIF
2. EXIF rotation: Aplicar rotacion automatica basada en la orientacion EXIF (comun en fotos de celular)
3. Strip EXIF: Eliminar datos EXIF sensibles (ubicacion GPS, modelo de dispositivo) por privacidad
4. Thumbnails: Generar 3 variantes redimensionadas:

5. Formato WebP: Todas las variantes se generan en WebP para optimizar tamano
6. Upload de variantes: Las 3 variantes se suben al bucket nvito-assets con keys derivados del original
7. Actualizar registro: Guardar URLs de thumbnails en el campo JSON del Media

Procesamiento asincrono

El procesamiento corre en una Bull queue (media-processing) con:

• Concurrencia: 2 jobs simultaneos por worker
• Timeout: 60 segundos por job
• Reintentos: 3 intentos con backoff exponencial
• Dead letter: Jobs fallidos se mueven a DLQ para revision manual

5. Categorias de Media

Cada archivo subido pertenece a una categoria que determina su bucket, procesamiento y visibilidad.

6. Limites por Plan

Cada organizacion tiene un plan que determina los limites de almacenamiento:

Verificacion de cuota

Antes de generar una presigned URL, el sistema calcula el almacenamiento usado:

1. Suma fileSize de todos los Media con status != ERROR de la organizacion
2. Compara con la cuota del plan
3. Si la suma + el nuevo archivo excede la cuota, retorna 413 Payload Too Large con detalle de uso

7. Infraestructura de Storage

4 Buckets

CDN y Storage por ambiente

Estructura de keys

Los archivos siguen una estructura de directorios logica:

{bucket}/
  {organizationId}/
    {eventId}/
      gallery/
        {uuid}.jpg          (original)
        {uuid}_thumb.webp    (150px)
        {uuid}_medium.webp   (400px)
        {uuid}_large.webp    (800px)
      hero/
        {uuid}.jpg
      audio/
        {uuid}.mp3
      video/
        {uuid}.mp4

8. Galeria Publica en Invitaciones

La seccion de galeria en las invitaciones publicas muestra las fotos del evento en una grilla responsive con lightbox.

Flujo de visualizacion

1. La invitacion HTML incluye una seccion gallery con URLs de thumbnails medium (400px)
2. Al hacer clic en una foto, se abre el lightbox con la variante large (800px)
3. Las imagenes se cargan desde CDN (cdn.nvito.mx) con cache headers agresivos

Galeria colaborativa (dia del evento)

Los invitados pueden subir fotos desde la app movil o PWA:

1. Invitado selecciona o toma una foto desde su dispositivo
2. La app solicita presigned URL y sube directo a S3
3. Confirma el upload y la foto entra en cola de procesamiento
4. Al estar lista, aparece automaticamente en la galeria del evento
5. El anfitrion puede moderar: aprobar o rechazar fotos desde el admin o la app

9. Audio Guestbook

El audio guestbook permite a los invitados grabar mensajes de voz para los anfitriones.

Grabacion

Flujo

1. Invitado presiona "Grabar mensaje" en la seccion de audio guestbook
2. La app solicita permiso de microfono
3. Graba hasta 60 segundos (limite configurable)
4. Muestra preview con boton de reproduccion
5. Invitado confirma y el audio se sube via presigned URL flow
6. El audio aparece en la lista de mensajes del evento
7. El anfitrion puede reproducir, descargar o eliminar mensajes

Metadata de audio

10. Diagrama del Flujo de Upload

11. Archivos Clave

nvito-api (Backend)

nvito-admin (Panel de Administracion)

nvito-client (App Nativa)

nvito-pwa (Progressive Web App)