AUTOMETA — Architecture Decision Records

ADR	Título	Estado	Decisores	Fecha	Relacionados
ADR-0001	Base de datos principal — PostgreSQL	Accepted	@elena, @marcos, @pablo	2026-05-12	ADR-0002
ADR-0002	Arquitectura de autenticación — Supabase Auth	Accepted	@elena, @sofia	2026-05-19	ADR-0001ADR-0003
ADR-0003	Cola de mensajes para jobs — BullMQ + Redis	Accepted	@marcos, @javi, @pablo	2026-05-28	ADR-0001

ADR-0001

Selección de base de datos principal

Accepted 2026-05-12 @elena · @marcos · @pablo Backend · Infraestructura

Implementado

Proposed → Accepted

Contexto

AUTOMETA necesita seleccionar la base de datos principal para la nueva arquitectura de microservicios. El sistema maneja datos de clientes EU (compliance GDPR, región aws eu-west-1), esquemas de automatizaciones con estructura semi-flexible, y reportes de analytics complejos. El equipo tiene experiencia en SQL pero no en bases de datos NoSQL avanzadas. Estimamos escalar de 500 a 5.000 clientes en 12 meses.

Drivers de decisión

✓ACID compliance para transacciones de billing
✓Soporte JSON/JSONB para configuraciones flexibles
✓Familiaridad del equipo (reduce tiempo de onboarding)
✓Gestión serverless o managed disponible en AWS eu-west-1
□Full-text search nativo (nice-to-have)

Opciones evaluadas

PostgreSQL 16 (RDS/Aurora) ELEGIDO

+ ACID, JSONB, full-text, PostGIS, equipo familiarizado
− Replicación más compleja; escala vertical antes que horizontal

MongoDB Atlas

+ Schema flexible, escala horizontal nativa
− Sin ACID multi-doc en nuestro tier, poca experiencia, coste mayor

PlanetScale (MySQL)

+ Branching de esquemas, serverless, DX excelente
− Sin FK nativas, vendor lock-in, sin JSONB avanzado

Decisión

Usaremos PostgreSQL 16 en Amazon RDS (Multi-AZ) en eu-west-1 como base de datos principal de todos los microservicios de AUTOMETA.

Justificación

PostgreSQL ofrece el mejor equilibrio: ACID compliance crítico para billing, JSONB para configuraciones de automatizaciones sin migraciones costosas, y el equipo ya domina SQL. RDS Multi-AZ garantiza el SLA de 99.9% requerido sin gestión de replicación manual. El cost-benefit frente a PlanetScale es positivo al no necesitar su feature de branching.

Consecuencias

Positivas

Transacciones seguras para billing
Menos servicios externos (no Elasticsearch)
Expertise del equipo aprovechado
GDPR: datos en eu-west-1 con RDS

Negativas

Necesitamos PgBouncer para conexiones
Leer replicas más pronto (~8K clientes)
Full-text search puede no escalar
Costo RDS Multi-AZ ~$200/mes extra

Notas de implementación

Usar JSONB para configuraciones de automatizaciones. PgBouncer para connection pooling. Streaming replication con 2 read replicas para analytics. Migración de datos existentes con pg_dump + transformación.

ADRs relacionados

ADR-0002

Arquitectura de autenticación y gestión de usuarios

Accepted 2026-05-19 @elena · @sofia Seguridad · Backend

En implementación

Proposed → Accepted

Contexto

El sistema de auth actual es un JWT custom con bcrypt en el monolito: sin MFA, sin SSO, sin gestión de sesiones avanzada. Clientes B2B piden SSO con Google Workspace y SAML. Con la migración a microservicios necesitamos auth centralizada que funcione cross-service. Requisito de compliance: audit logs de acceso, datos de auth en EU.

Drivers de decisión

✓SSO: Google Workspace + SAML (requerido por 3 clientes enterprise)
✓MFA obligatorio para acceso admin
✓Datos de usuarios en EU (GDPR)
✓SDK TypeScript de calidad
✓Precio predecible con crecimiento a 5K usuarios
□Webhook de eventos de auth para auditoría

Opciones evaluadas

Supabase Auth ELEGIDO

+ Open source, PostgreSQL-native (ya lo usamos), EU hosting, SDK TS excelente, MFA, SSO en plan Team
− SAML solo en plan Enterprise ($599/mes); migración de usuarios existente

Auth0 (Okta)

+ Maduro, SAML en plan básico, excelente docs
− Caro en escala ($23/mes por 1K MAU extra), vendor lock-in, datos pueden ir a US

Clerk

+ DX increíble, UI pre-built, webhooks nativos
− Sin región EU garantizada, precio escala lineal, SAML solo Enterprise

JWT custom propio

+ Control total, coste ~0
− 4-6 semanas de desarrollo, riesgo seguridad, no scale, sin SSO

Decisión

Adoptaremos Supabase Auth (plan Team) para autenticación centralizada, comenzando con OAuth/Google y MFA, con SAML diferido hasta confirmar demanda enterprise.

Justificación (Y-Statement)

En el contexto de construir auth centralizada para microservicios con GDPR EU, frente a la necesidad de SSO, MFA y control de costes, decidimos por Supabase Auth y en contra de Auth0 y Clerk, para lograr integración nativa con nuestra PostgreSQL y hosting EU, aceptando que SAML enterprise queda diferido hasta Q4 2026.

Consecuencias

Positivas

Auth en misma infra PostgreSQL
EU data residency garantizada
MFA y OAuth disponibles inmediato
Costo: $25/mes vs $200+ de Auth0

Negativas

SAML requiere upgrade ($599) si hay demanda
Migración JWT existente ~1 semana
Supabase menos maduro que Auth0
Dependencia de roadmap Supabase

Plan de mitigación SAML

Evaluar demanda SAML en revisión Q3 2026. Si más de 5 clientes enterprise solicitan SAML, hacer upgrade a Supabase Enterprise o evaluar migración a Auth0. Diseñar capa de abstracción en el SDK interno para facilitar futuros cambios.

ADRs relacionados

ADR-0003

Cola de mensajes para jobs de automatización

Accepted 2026-05-28 @marcos · @javi · @pablo Backend · Infraestructura · Performance

En producción

Proposed → Accepted

Contexto

AUTOMETA procesa ~80.000 jobs de automatización al día (envíos de email, webhooks, actualizaciones de CRM, publicaciones en redes sociales). El sistema actual usa cron jobs en el monolito con pg_notify: no hay retry automático, visibilidad cero de fallos, y los picos de carga (campañas masivas) generan timeouts. La nueva arquitectura requiere una cola dedicada con prioridades, retry exponencial y monitoreo.

Drivers de decisión

✓Retry con backoff exponencial y dead-letter queue
✓Prioridades de jobs (enterprise > free)
✓Dashboard de monitoreo de jobs en tiempo real
✓TypeScript SDK de primera clase
✓Soportar picos de 10K jobs/hora sin degradación
□Rate limiting por cliente (roadmap Q3)

Benchmark de opciones

Opción	Throughput	Gestión	Coste
BullMQ + Redis ✓	50K+/min	Baja	~$30/mes
AWS SQS + Lambda	Ilimitado	Media	$0.40/Mjobs
RabbitMQ	20K+/min	Alta	~$80/mes

Decisión

Adoptaremos BullMQ con Redis (ElastiCache eu-west-1) como sistema de colas para todos los jobs de automatización de AUTOMETA.

Justificación

BullMQ ofrece el mejor ajuste para nuestro stack TypeScript: SDK nativo, prioridades y colas múltiples, retry con backoff exponencial y Bull Board para dashboard de monitoreo sin desarrollar UI adicional. Redis ElastiCache en eu-west-1 cubre compliance y latencia. El throughput de 50K+ jobs/minuto supera ampliamente nuestra necesidad de ~56 jobs/minuto promedio (80K/día), con headroom para picos de campañas. SQS fue descartado por complejidad de prioridades y sin visibilidad nativa.

Arquitectura de colas

// Estructura de colas BullMQ
queues/
├── email-campaigns     // prioridad 1
├── webhook-delivery    // prioridad 2
├── crm-sync            // prioridad 3
├── social-publish      // prioridad 4
└── dead-letter         // retry agotado

// Retry config
attempts: 5
backoff: { type: 'exponential', delay: 2000 }

Consecuencias

Positivas

Retry automático elimina fallos silenciosos
Bull Board: visibilidad de jobs en tiempo real
Prioridades: enterprise primero
TS-native, integración con Fastify limpia

Negativas

Redis adicional a gestionar (ElastiCache)
Redis no es persistencia duradera (riesgo de pérdida)
Migración de crons existentes ~2 semanas
Sin replay de jobs histórico

ADRs relacionados