Arquitectura
Visión general del sistema
Cómo se conectan los componentes que hacen posible una campaña de MediNodo, desde la creación del envío hasta el registro del interés y la gestión de fallos.
Resumen
El sistema se organiza en cuatro planos que colaboran pero mantienen responsabilidades separadas:
listmonk compone las campañas y las entrega a través de Amazon SES por SMTP autenticado.
El destinatario hace click, llega a la landing en Vercel y confirma su interés vía FastAPI.
SES publica rebotes y reclamos por SNS hacia un webhook de listmonk, que aplica blocklist.
PostgreSQL persiste todo; Cloudflare enruta y protege los hostnames públicos.
Mapa de alto nivel
Este diagrama muestra el camino principal de una campaña sin los detalles de fallo, que se documentan por separado en Flujos.
Capas del sistema
| Capa | Componentes | Función |
|---|---|---|
| Composición | listmonk, PostgreSQL | Definir campañas, listas y suscriptores; generar enlaces individuales. |
| Transporte | Amazon SES, AWS IAM | Autenticar y entregar el correo a los proveedores de destino. |
| Borde | Cloudflare DNS, Cloudflare Tunnel, Caddy (local) | Resolver dominios, publicar autenticación y exponer servicios privados. |
| Experiencia | Vercel (Next.js), Turnstile, Upstash | Servir la landing y proteger el formulario de interés. |
| Aplicación | FastAPI | Validar campaña-suscriptor, aplicar idempotencia y registrar el interés. |
| Feedback | Amazon SNS, listmonk | Propagar hard bounces y complaints y aplicar blocklist. |
Matriz de responsabilidad
Cada componente hace una cosa y la hace bien. Estos límites evitan solapamientos y facilitan la operación.
| Componente | Sí es responsable de… | No es responsable de… |
|---|---|---|
| listmonk | Decidir a quién enviar, estado de campaña y registro del click. | Entregar correo directamente a Internet. |
| Amazon SES | Transportar el mensaje y generar feedback de entrega. | Administrar listas ni campañas. |
| Amazon SNS | Transportar eventos de bounce y complaint. | Decidir el registro o la blocklist (eso lo hace listmonk). |
| FastAPI | Registrar el interés confirmado en la landing. | Registrar el click del email (eso lo hace listmonk). |
| Cloudflare | Proteger y enrutar los hostnames públicos. | Almacenar datos de negocio. |
| PostgreSQL | Persistir configuración, clicks, bounces e interés. | Tomar decisiones de enrutamiento o entrega. |
Buenas prácticas
- Mantener la separación de planos: no mover a la landing la lógica de blocklist ni al backend el registro del click.
- Publicar los servicios privados únicamente a través de Cloudflare Tunnel en producción, nunca exponiendo puertos.
- Tratar a PostgreSQL como única fuente de verdad de negocio y respaldarlo de forma cifrada.
Consideraciones
Cuotas y sandbox de SES
La salida del sandbox y las cuotas de Amazon SES se administran por región y condicionan el volumen de envío. Es un límite a vigilar antes de escalar campañas.