1. Contexto del Sistema (C4)
Muestra los actores principales, las cuatro aplicaciones y los servicios externos con los que interactuan.
Diagrama de Contexto (C4 Level 1)
AnfitrionOrganiza eventos
InvitadoRecibe invitaciones
Super AdminGestiona plataforma
StaffEquipo de evento
Aplicaciones Nvito
nvito-adminNext.js 16 — Panel Admin
nvito-invitationsNext.js 16 — SSG/ISR
nvito-clientExpo 54 — App Movil
nvito-pwaNext.js 16 — PWA
Sitios Estaticos (Cloudflare Pages)
nvito-landingAstro 5 — Landing page
Aplicaciones Nvito
nvito-apiNestJS 11 — Backend
ClerkAuth + RBAC
PostgreSQLNeon — BD principal
RedisUpstash — Colas/Cache
Cloudflare R2Object Storage
Email SMTPEnvio de correos
TwilioWhatsApp/SMS
Expo PushNotificaciones movil
Referencia completa: Arquitectura del Sistema
2. Flujo de Request HTTP
Secuencia completa de un request autenticado desde el frontend hasta la base de datos.
Flujo HTTP — Request Autenticado
Client
API
ClerkAuthGuard
TenantMiddleware
Controller
Service
Prisma
PostgreSQL
GET /v1/events (Bearer JWT)
REST
Verificar JWT
Clerk.verifyJWT()
Buscar usuario en BD
Resolver rol + org
AuthenticatedUser
SET LOCAL app.current_tenant_id
RLS context activo
Ejecutar handler
Logica de negocio
Query tipado
SQL con RLS filter
Rows filtradas por tenant
Entidades tipadas
DTO de respuesta
Response
200 OK + JSON
Client
API
ClerkAuthGuard
TenantMiddleware
Controller
Service
Prisma
PostgreSQL
3. Deployment y CI/CD
Flujo desde el push en GitLab hasta el deploy en contenedores Docker via Coolify.
Pipeline CI/CD
GitLab CI Pipeline
LintESLint + TypeCheck
TestVitest / Jest
MigratePrisma Deploy
Coolify Deploy
Docker BuildImagen standalone
Health CheckReadiness probe
DeployZero-downtime
Infraestructura
VPSCoolify host
Neon PGPostgreSQL
Upstash RedisCache + Queues
Cloudflare R2Object Storage
DeveloperPush a GitLab
GitLabRepositorio
4. Flujo de Autenticación
Proceso completo desde login del usuario hasta la verificacion del JWT en cada request.
Flujo de Autenticacion — Clerk + JWT
Usuario
nvito-admin
Clerk
nvito-api
ClerkAuthGuard
PostgreSQL
Login con credenciales
Autenticar via Clerk SDK
Session + JWT firmado
GET /v1/events (Bearer JWT)
REST
Interceptar request
Clerk.verifyJWT()
SELECT user WHERE clerk_id = sub
User + role + organizationId
Construir AuthenticatedUser
req.user = AuthenticatedUser
200 OK + datos del evento
Renderizar dashboard
Usuario
nvito-admin
Clerk
nvito-api
ClerkAuthGuard
PostgreSQL
5. Ciclo de Vida de Invitaciones
Maquina de estados que controla el ciclo de vida de cada invitación en la plataforma. Aplica tanto a invitaciones internas (INTERNAL) como externas (EXTERNAL).
Ciclo de Vida de Invitaciones
In Construction
submit()Enviar a revision
Unpublished
approve()Aprobar y publicar
Published
close()Cerrar evento
Closed
PUBLISHED→UNPUBLISHEDunpublish()CLOSED→PUBLISHEDreopen()UNPUBLISHED→IN_CONSTRUCTIONreject()Convenciones de Diagramas
| Elemento | Color | Significado |
|---|---|---|
| Azul oscuro | #08427B | Actores / personas |
| Azul medio | #438DD5 | Aplicaciones del sistema |
| Gris | #999999 | Servicios externos |
| Amarillo | #e8a838 | Stages de CI/CD |
| Verde | #6db33f | Stages de deploy |