JaureguiChat — Documentación Técnica

01 — Arquitectura

Infraestructura AWS

Arquitectura 100% serverless desplegada en eu-west-1. Sin servidores que gestionar. El frontend se sirve desde S3 a través de CloudFront. El backend son 5 funciones Lambda invocadas por API Gateway.

02 — Funciones Lambda

5 Lambdas, 9 endpoints

Cada Lambda tiene una responsabilidad única. Se ejecutan solo cuando llega una petición y se apagan al terminar — coste cero en reposo.

pingme-auth Autenticación y usuarios

Gestiona el ciclo completo de autenticación usando Amazon Cognito. Al registrarse genera un ID anónimo PM-XXXX aleatorio que se guarda en DynamoDB y es la identidad del usuario en la app.

POST/auth/registro

Crea el usuario en Cognito, envía email de verificación y guarda el PM-XXXX en DynamoDB. Devuelve el userId generado.

POST/auth/login

Verifica credenciales con Cognito. Devuelve tres tokens: IdToken (identidad), AccessToken (acceso a API) y RefreshToken (renovación). También devuelve el userId y nombre del usuario.

POST/auth/verificar

Confirma el email del usuario con el código de 6 dígitos enviado por Cognito tras el registro. Sin verificar, el login no está permitido.

POST/auth/refresh

Renueva el IdToken y AccessToken usando el RefreshToken cuando expiran (1 hora). Permite sesiones persistentes sin volver a hacer login.

pingme-conversaciones Historial de conversaciones

Carga la lista de conversaciones del usuario al abrir la app. Cada entrada contiene el último mensaje y timestamp para mostrar la vista previa en la barra lateral, ordenadas de más a menos reciente.

GET/conversaciones/{userId}

Consulta la tabla conversaciones de DynamoDB filtrando por userId. Devuelve todas las conversaciones activas con su último mensaje y timestamp.

pingme-ws-connect Conexión WebSocket

Se ejecuta automáticamente cuando un usuario abre la app y el cliente React establece la conexión WebSocket. Registra la presencia online del usuario para poder enviarle mensajes en tiempo real.

WS$connect

Guarda el connectionId generado por API Gateway en la tabla conexiones de DynamoDB. Este ID es el canal directo para enviar mensajes al usuario. TTL de 24 horas como seguridad si no se ejecuta el disconnect.

pingme-ws-disconnect Desconexión WebSocket

Se ejecuta cuando el usuario cierra la app o pierde la conexión. Limpia el registro de presencia para que el sistema sepa que ese usuario está offline y los mensajes deben guardarse para entrega diferida.

WS$disconnect

Busca el userId asociado al connectionId que se ha cerrado y borra su entrada de la tabla conexiones. A partir de ese momento el usuario figura como offline.

pingme-ws-message Motor de mensajería

El núcleo del sistema. Maneja el envío, recuperación y estados de los mensajes. Si el destinatario está online entrega el mensaje en menos de 100ms. Si está offline lo persiste en DynamoDB para entrega cuando reconecte.

WSsendMessage

Guarda el mensaje en DynamoDB, actualiza la vista previa de la conversación para ambos usuarios y si el destinatario está online le entrega el mensaje al instante vía post_to_connection de API Gateway.

WSgetMessages

Devuelve el historial completo de una conversación desde DynamoDB ordenado por timestamp. Se llama al abrir una conversación o al reconectar para recuperar mensajes pendientes.

WSmarkAsRead

Marca un mensaje como leído actualizando el campo leido en DynamoDB. Permite implementar confirmaciones de lectura en el frontend.

03 — Base de datos

4 tablas DynamoDB

Modelo NoSQL con TTL automático. Sin gestión de infraestructura, pago por operación.

usuarios

Almacena el perfil de cada usuario: su ID anónimo PM-XXXX, email y nombre. Se escribe una vez al registrarse.

mensajes

Todos los mensajes con su conversationId, timestamp, remitente, destinatario y estado de lectura. TTL de 90 días.

conexiones

Usuarios online ahora mismo. Cada entrada vincula un userId con el connectionId activo de API Gateway. TTL de 24 horas.

conversaciones

Vista previa de cada conversación por usuario — último mensaje y timestamp para mostrar la lista lateral sin leer todos los mensajes.

04 — Flujo en tiempo real

Cómo viaja un mensaje

Recorrido completo de un mensaje cuando Diego manda "Hola" a Maria estando los dos conectados.

React envía el mensaje por WebSocket. El cliente manda un frame TCP cifrado con TLS al API Gateway WebSocket en eu-west-1.

API Gateway lee el campo action y enruta. Encuentra sendMessage en su tabla de rutas y despierta la Lambda pingme-ws-message.

Lambda identifica al remitente. Busca en la tabla conexiones quién tiene el connectionId entrante y encuentra a Diego (PM-B93F).

Persiste el mensaje. Guarda en tabla mensajes y actualiza tabla conversaciones para ambos usuarios con el nuevo último mensaje.

Busca si Maria está online. Consulta tabla conexiones con el userId de Maria. Si existe, obtiene su connectionId activo.

Entrega instantánea. Llama a apigateway.post_to_connection(connectionId_maria). API Gateway entrega el frame TCP a Maria en menos de 100ms. Si está offline el mensaje queda en DynamoDB y se entrega cuando reconecte.

05 — Seguridad

Capas de seguridad

Cada capa protege contra un vector diferente.

TLS en tránsito. Todo el tráfico cifrado con TLS 1.2+. CloudFront fuerza HTTPS, el WebSocket usa wss://. El bucket S3 es privado y solo accesible a través de CloudFront mediante Origin Access Control.

JWT con Cognito. Tokens firmados con RS256. Expiración de 1 hora, renovación automática con refresh token de 30 días. Las claves públicas de Cognito verifican la firma sin contactar a ningún servidor.

CORS estricto. API Gateway solo acepta peticiones de dominios autorizados. La whitelist se comprueba dinámicamente en cada Lambda — si el origen no está permitido la petición es rechazada por el navegador.

IAM mínimo privilegio. Cada Lambda tiene permisos solo para sus tablas específicas. pingme-conversaciones solo puede leer la tabla conversaciones. pingme-auth solo puede tocar la tabla usuarios y llamar a Cognito.

TTL automático. Mensajes borrados automáticamente a los 90 días, conexiones a las 24 horas. DynamoDB limpia sin intervención manual ni coste adicional.