1. Maquina de Estados
Cada invitación en Nvito sigue un ciclo de vida de 4 estados. Las transiciones estan controladas por ApprovalWorkflowService, que valida las precondiciones de cada cambio de estado.
1.1 Diagrama de Estados
Maquina de Estados — Invitacion
IN_CONSTRUCTION
UNPUBLISHED
PUBLISHED
CLOSED
in-construction→unpublishedSubmit for Approvalunpublished→publishedApproveunpublished→in-constructionReject / Request Changespublished→unpublishedUnpublishpublished→closedClose / Evento completadoclosed→publishedReopenin-construction→in-constructionEditar / Guardar1.2 Transiciones
| Transición | De | A | Actor | Validaciones |
|---|---|---|---|---|
| Crear | [*] | IN_CONSTRUCTION | Usuario | Max 3 invitaciones por evento, auto-genera slug |
| Submit | IN_CONSTRUCTION | UNPUBLISHED | Usuario | Secciones requeridas presentes (solo internas) |
| Approve | UNPUBLISHED | PUBLISHED | Usuario | Genera HTML (internas) o verifica htmlUrl (externas) |
| Reject | UNPUBLISHED | IN_CONSTRUCTION | Usuario | Requiere razon de rechazo |
| Unpublish | PUBLISHED | UNPUBLISHED | Usuario | Webhook de despublicación |
| Close | PUBLISHED | CLOSED | Usuario o Sistema | Registra closeReason y closedBy |
| Reopen | CLOSED | PUBLISHED | Usuario | Evento debe estar ACTIVE, fecha vigente |
2. Tipos de Invitación (InvitationSource)
Nvito soporta dos origenes de invitación, discriminados por el enum InvitationSource:
2.1 Invitación Interna (INTERNAL)
Creada con el motor de templates, IA conversacional y editor visual de Nvito.
Caracteristicas:
- Template base seleccionado del catálogo o generado por IA
- Secciones editables: Hero, RSVP, Location, Itinerary, Gallery, GiftRegistry, Accommodation, DressCode, FAQ
- Temas personalizables con paleta de colores y tipografias
- Transiciones fullpage (27 tipos: 10 clasicas + 17 cinematograficas)
- Pantallas de carga (25 tipos: 8 CSS + 17 Canvas)
- Versiónamiento interno (max 50 versiones)
- Generación HTML automática al publicar
2.2 Invitación Externa (EXTERNAL)
HTML disenado fuera de Nvito, cargado manualmente.
Caracteristicas:
- Upload de archivo HTML (max 5MB)
- Validación de seguridad en 9 pasos (
HtmlValidatorService) - Sin editor visual — re-upload completo para cambios
- Sin versionamiento (siempre versión 1)
- Sin secciones ni temas de Nvito
- Publicación directa (skip HTML generation)
2.3 Comparativa
| Aspecto | INTERNAL | EXTERNAL |
|---|---|---|
| Creación | Template + IA + Editor | Upload HTML |
| Edicion | Visual, por secciones | Re-upload completo |
| Versiónes | Si (max 50) | No |
| Secciones | Si (Hero, RSVP, etc.) | No |
| Temas | Si | No |
| Transiciones | Si (27 tipos) | No |
| Loaders | Si (25 tipos) | No |
| Publicación | Genera HTML + CDN | Verifica htmlUrl |
| Analiticas | Si | Si |
| Preview | Si | Si |
| RSVP | Si | Si (si incluye formulario) |
3. Flujo de Creación — Invitación Interna
Creacion — Invitacion Interna
Organizador
nvito-api
PostgreSQL
IA Service
POST /invitations (eventId, type: INTERNAL)
Validar max 3 invitaciones por evento
Generar slug unico (nanoid)
Crear invitacion (estado: IN_CONSTRUCTION)
Invitacion creada
201 Created
Configuracion del contenido
Seleccionar template base
Configurar secciones (Hero, RSVP, Location...)
Seleccionar tema y colores
Configurar transicion y loader
opt[IA Conversacional]
POST /invitations/:id/ai/generate
Generar contenido segun contexto
Textos sugeridos
Contenido generado
POST /invitations/:id/submit-for-approval
Validar secciones requeridas
Cambiar estado a UNPUBLISHED
200 OK
Organizador
nvito-api
PostgreSQL
IA Service
4. Flujo de Creación — Invitación Externa
Creacion — Invitacion Externa
Organizador
nvito-api
HtmlValidatorService
S3/CDN
PostgreSQL
POST /invitations (eventId, type: EXTERNAL)
Validar max 3 invitaciones por evento
Generar slug unico
Crear invitacion (estado: IN_CONSTRUCTION, source: EXTERNAL)
Invitacion creada
201 Created
POST /invitations/:id/upload-external (HTML file)
validate(htmlContent)
9 pasos de validacion
1. Verificar tamano (max 5MB)
2. Verificar estructura HTML basica
3. Detectar scripts maliciosos
4. Verificar encoding UTF-8
5. Sanitizar atributos peligrosos
6. Verificar URLs externas (whitelist)
7. Detectar iframes no permitidos
8. Verificar meta tags requeridos
9. Validar tamano post-sanitizacion
Validacion OK
Upload HTML sanitizado
htmlUrl
Guardar htmlUrl y externalHtmlRaw
200 OK (HTML validado y subido)
POST /invitations/:id/submit-for-approval
Cambiar estado a UNPUBLISHED
200 OK
Organizador
nvito-api
HtmlValidatorService
S3/CDN
PostgreSQL
5. Pipeline de Publicación
El flujo de publicación es el proceso más critico del ciclo de vida. Transforma una invitación aprobada en una página web accesible publicamente.
Pipeline de Publicacion — Invitacion
Organizador
nvito-api
ApprovalWorkflowService
HtmlGenerationService
DocumentGeneratorService
S3/CDN
EventLifecycleService
nvito-invitations
POST /invitations/:id/approve
approve(invitationId)
Validar transicion UNPUBLISHED -> PUBLISHED
alt[source === INTERNAL]
generate(invitation)
buildDocument(sections, theme, transitions)
Compilar HTML + CSS + JS
Inyectar transiciones y loaders
Inyectar analytics script
Upload (HTML, CSS, assets)
CDN URLs (htmlUrl, cssUrl, jsUrl)
URLs generadas
else[source === EXTERNAL]
Verificar que htmlUrl existe en S3
Cambiar estado a PUBLISHED
Registrar publishedAt, publishedBy
Incrementar publishCount
activateEventOnPublish(eventId)
Si evento en DRAFT, transiciona a ACTIVE
POST /api/revalidate (paths: [/i/slug])
Regenerar pagina estatica (ISR)
Revalidacion completada
Invitacion publicada
200 OK
Organizador
nvito-api
ApprovalWorkflowService
HtmlGenerationService
DocumentGeneratorService
S3/CDN
EventLifecycleService
nvito-invitations
6. Versiónamiento (Solo Internas)
Las invitaciones internas mantienen un historial de versiones que permite rollback.
| Aspecto | Detalle |
|---|---|
| Max versiones | 50 por invitación |
| Que se versióna | Contenido de secciones, configuración de tema, transiciones, loaders |
| Cuando se crea versión | Al guardar cambios significativos (no auto-save) |
| Rollback | Restaura una versión anterior como versión actual |
| Impacto en publicación | El rollback no república — requiere nuevo ciclo de aprobacion |
7. Secciones de Invitación (Solo Internas)
Las invitaciones internas se componen de secciones modulares:
| Sección | Requerida | Descripción |
|---|---|---|
| Hero | Si | Portada con nombres, fecha y mensaje principal |
| RSVP | Si | Formulario de confirmación de asistencia |
| Location | No | Mapa y direccion del venue |
| Itinerary | No | Programa del evento con horarios |
| Gallery | No | Galería de fotos |
| GiftRegistry | No | Mesa de regalos y fondos de efectivo |
| Accommodation | No | Opciones de hospedaje |
| DressCode | No | Código de vestimenta |
| FAQ | No | Preguntas frecuentes |
Orden de secciones: Configurable por el usuario via drag-and-drop. Se almacena como array ordenado visibleSections.
8. Mecanismos de Cierre
Una invitación puede cerrarse por múltiples razones:
| Mecanismo | closeReason | Actor | Descripción |
|---|---|---|---|
| Manual | MANUAL | Usuario | El organizador cierra la invitación explicitamente |
| Evento completado | EVENT_COMPLETED | Sistema | EventSchedulerService cierra invitaciones al completar evento |
| Evento cancelado | EVENT_CANCELLED | Sistema | Al cancelar evento, todas las invitaciones se cierran |
8.1 Reapertura
Una invitación cerrada puede reabrirse si:
- El evento está en estado
ACTIVE - La fecha del evento no ha pasado
- El usuario tiene rol
OWNERoADMIN
La reapertura cambia el estado de CLOSED a PUBLISHED y dispara revalidación ISR.
9. Restricciones y Limites
| Restriccion | Valor |
|---|---|
| Max invitaciones por evento | 3 |
| Max versiones por invitación (interna) | 50 |
| Max tamano HTML externo | 5 MB |
| Slug | Unico global, alfanumerico + guiones, max 200 chars |
| Secciones requeridas (interna) | Hero + RSVP |
10. Archivos Clave
| Archivo | Ubicación | Responsabilidad |
|---|---|---|
invitations.service.ts | src/modules/invitations/ | CRUD de invitaciones, validaciones de negocio |
invitation-lifecycle.service.ts | src/modules/invitations/services/ | Gestión de estados y transiciones |
approval-workflow.service.ts | src/modules/invitations/services/ | Pipeline de aprobacion y publicación |
html-generation.service.ts | src/modules/invitations/services/ | Generación de HTML para invitaciones internas |
document-generator.service.ts | src/modules/invitations/services/ | Compilacion del documento final (HTML + CSS + JS) |
html-validator.service.ts | src/modules/invitations/services/ | Validación de seguridad de HTML externo (9 pasos) |
external-invitation.service.ts | src/modules/invitations/services/ | Upload, re-upload y download de HTML externo |
sections.service.ts | src/modules/invitations/services/ | CRUD de secciones de invitación |
themes.service.ts | src/modules/invitations/services/ | Configuración de temas visuales |
11. Relación con Otros Flujos
| Flujo relacionado | Relación |
|---|---|
| Ciclo de Vida del Evento | La publicación activa el evento; el cierre del evento cierra invitaciones |
| Flujo del Invitado | Los invitados interactuan con invitaciones publicadas (RSVP, visualización) |
| Flujo de Comunicaciones | Las campanas incluyen el link a la invitación publicada |