Arquitectura AWS

Sistema de traduccion serverless con SQS + Lambda

ProduccionAlta DisponibilidadAuto-scaling

Resumen

LectorAI utiliza AWS para procesar traducciones de forma escalable y resiliente. La arquitectura serverless garantiza que las traducciones nunca se interrumpen durante deployments.

Diagrama de Arquitectura

                              AWS Cloud (us-east-2)
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  ┌─────────────────┐     ┌─────────────────┐     ┌───────────────────────┐ │
│  │   SQS FIFO      │     │   AWS Lambda    │     │   Secrets Manager     │ │
│  │   Queues        │────▶│   (Traductor)   │◀────│   (API Keys + DB)     │ │
│  └─────────────────┘     └────────┬────────┘     └───────────────────────┘ │
│          ▲                        │                                         │
│          │                        │ ┌───────────────────────────────────┐   │
│          │                        │ │       CIRCUIT BREAKER             │   │
│          │                        ├─▶  OpenAI ──▶ Gemini ──▶ Claude     │   │
│          │                        │ │       (Fallback Automatico)       │   │
│          │                        │ └───────────────────────────────────┘   │
│          │                        │                                         │
│  ┌───────┴─────────┐     ┌────────▼────────┐     ┌───────────────────────┐ │
│  │   SQS DLQ       │     │   CloudWatch    │     │   SNS Alertas         │ │
│  │   (Fallidos)    │     │   (Logs+Alarms) │────▶│   (Notificaciones)    │ │
│  └─────────────────┘     └─────────────────┘     └───────────────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
           │
           │ HTTPS (Encolar jobs + Webhook resultados)
           │
┌──────────┼──────────────────────────────────────────────────────────────────┐
│          │                    Contabo Server (Easypanel)                    │
│  ┌───────┴─────────┐     ┌─────────────────┐     ┌───────────────────────┐ │
│  │   Next.js App   │     │   PostgreSQL    │     │   Admin Dashboard     │ │
│  │   (API + UI)    │────▶│   (Datos)       │◀────│   (Costos + DLQ)      │ │
│  └─────────────────┘     └─────────────────┘     └───────────────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Circuit Breaker Pattern

Protege el sistema cuando una API externa falla repetidamente. Implementado por proveedor (OpenAI, Anthropic, Google).

CLOSED

Normal

Todo funciona correctamente. Las peticiones se envian al proveedor sin restricciones.

OPEN

Bloqueado

5+ fallos consecutivos. Las peticiones se rechazan inmediatamente y se usa fallback.

HALF_OPEN

Probando

Despues de 60s, permite 2 peticiones de prueba. Si funcionan, vuelve a CLOSED.

Diagrama de Estados

                    ┌──────────────────────────────────────────────────────┐
                    │                                                      │
                    ▼                                                      │
              ┌──────────┐     5 fallos     ┌──────────┐    60s timeout   │
              │  CLOSED  │ ───────────────▶ │   OPEN   │ ─────────────────┤
              └──────────┘                  └──────────┘                  │
                    ▲                              │                      │
                    │                              ▼                      │
                    │        exito          ┌───────────┐     fallo       │
                    └─────────────────────── │ HALF_OPEN │ ───────────────┘
                                            └───────────┘
                                           (2 peticiones)

Threshold:5 fallos

Timeout:60 segundos

Pruebas:2 peticiones

Fallback Automatico de Modelos

Cuando el circuito de un proveedor se abre, el sistema automaticamente cambia a un modelo alternativo para garantizar continuidad.

Modelo Principal	Fallback 1	Fallback 2
`gpt-4o-mini`	`gemini-2.0-flash`	`claude-3-haiku`
`gpt-4o`	`gemini-1.5-pro`	`claude-sonnet-4`
`claude-3-haiku`	`gemini-2.0-flash`	`gpt-4o-mini`
`claude-sonnet-4`	`gemini-1.5-pro`	`gpt-4o`
`gemini-2.0-flash`	`gpt-4o-mini`	`claude-3-haiku`
`gemini-1.5-pro`	`gpt-4o`	`claude-sonnet-4`

El modelo utilizado se registra en cada traduccion. Visible en logs y dashboard de costos.

Dead Letter Queue + Clasificacion de Errores

Los jobs que fallan despues de 3 reintentos se envian a la DLQ y se clasifican automaticamente para facilitar la resolucion.

Categorias de Errores

Categoria	Descripcion	Accion Recomendada
RATE_LIMIT	Error 429, quota excedida	Esperar y reintentar automaticamente
AUTH_ERROR	API key invalida o expirada	Verificar API keys en Secrets Manager
NETWORK_ERROR	Timeout, conexion fallida	Reintentar (problema transitorio)
VALIDATION	Datos de entrada invalidos	Revisar payload del job
MODEL_ERROR	Error del modelo (contexto muy largo)	Dividir capitulo o usar otro modelo
INTERNAL	Error interno no clasificado	Revisar logs con traceId

Dashboard de Jobs Fallidos

Gestiona, reintenta y resuelve jobs fallidos desde el panel de administracion.

Ver Dashboard

Trace ID Correlation

Cada job genera un traceId unico que permite rastrear toda la ejecucion end-to-end en CloudWatch.

Ejemplo de Log Estructurado

{
  "timestamp": "2025-12-19T04:03:55.582Z",
  "level": "INFO",
  "message": "Chapter translation completed",
  "traceId": "tr-mjcche7y-7kzgru",
  "bookId": "cm5abc123",
  "chapterId": "cm5def456",
  "requestedModel": "gpt-4o-mini",
  "actualModel": "gemini-2.0-flash",
  "usedFallback": true,
  "duration": 45000,
  "tokensUsed": 12500,
  "requestId": "2895ce9e-6f71-58c0-88e2-af20bfa63f89"
}

Buscar logs por traceId:

aws logs filter-log-events --log-group-name /aws/lambda/lectorai-translate-chapter --filter-pattern "tr-mjcche7y-7kzgru"

Modos de Procesamiento

AWS SQS + Lambda

Produccion

Traducciones NO se interrumpen durante deploys

Escalado automatico segun demanda

Circuit Breaker + Fallback automatico

Dead Letter Queue con clasificacion de errores

Trace ID para debugging end-to-end

BullMQ (Redis)

Fallback

Workers Node.js locales

Ideal para desarrollo local

Se interrumpe durante deploys

Activado con USE_AWS_QUEUE=false

Sistema de Traduccion (3 Pases)

Cada capitulo se traduce en 3 pases para garantizar maxima calidad:

Traduccion Inicial

Traduccion directa del texto original al espanol, manteniendo el estilo y tono.

Revision de Consistencia

Verifica terminos del glosario, nombres propios y consistencia de estilo con capitulos anteriores.

Pulido Final

Refina la fluidez y naturalidad del texto, asegurando una lectura agradable.

CloudWatch Alarms

Alertas configuradas para detectar problemas antes de que afecten a los usuarios.

Alarma	Metrica	Umbral	Accion
lectorai-translate-dlq-messages	ApproximateNumberOfMessagesVisible	> 0	SNS Alert
lectorai-lambda-errors	Errors	> 5 en 5 min	SNS Alert
lectorai-lambda-duration	Duration	> 600000ms	SNS Warning
lectorai-lambda-throttles	Throttles	> 10 en 5 min	SNS Warning

Componentes AWS

SQS Queues (FIFO)

Cola	Proposito	Timeout
lectorai-translate-queue.fifo	Trabajos de traduccion	5 min
lectorai-translate-dlq.fifo	Traducciones fallidas	-
lectorai-generate-queue.fifo	Generacion EPUB/PDF	10 min
lectorai-extract-queue.fifo	Extraccion de texto	5 min

Configuracion: Retencion 14 dias, Content-Based Deduplication, Max Receive Count: 3

Lambda Functions

Funcion	Memoria	Timeout	Features
lectorai-translate-chapter	512 MB	15 min	3 PasesCircuit BreakerFallback

Secrets Manager

Secret	Contenido
lectorai/api-keys	OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_API_KEY
lectorai/database	DATABASE_URL

Dashboard de Costos

Monitorea el costo de traducciones por modelo, usuario y periodo de tiempo.

Precios por Modelo (1M tokens)

Modelo	Input	Output
gpt-4o-mini	$0.15	$0.60
gemini-2.0-flash	$0.075	$0.30
claude-3-haiku	$0.25	$1.25
gpt-4o	$2.50	$10.00
gemini-1.5-pro	$1.25	$5.00
claude-sonnet-4	$3.00	$15.00

Dashboard de Costos

Analiza costos por modelo, usuario y periodo. Identifica traducciones costosas.

Ver Dashboard

Variables de Entorno

# Activar modo AWS SQS
USE_AWS_QUEUE=true

# URLs de las colas SQS FIFO
AWS_SQS_TRANSLATE_QUEUE_URL=https://sqs.us-east-2.amazonaws.com/.../lectorai-translate-queue.fifo
AWS_SQS_GENERATE_QUEUE_URL=https://sqs.us-east-2.amazonaws.com/.../lectorai-generate-queue.fifo
AWS_SQS_EXTRACT_QUEUE_URL=https://sqs.us-east-2.amazonaws.com/.../lectorai-extract-queue.fifo

# Credenciales AWS (ya configuradas para S3)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-2

Estado del Sistema

Pagina de Status

Verifica el modo de procesamiento actual y el estado de todos los servicios en tiempo real.

Ver Status

Costos AWS Estimados

Servicio	Uso	Costo/Mes
SQS	100K mensajes	~$0.40
Lambda	10K invocaciones x 3min	~$15
Secrets Manager	3 secrets	~$1.20
CloudWatch	Logs + Metrics + Alarms	~$5
Total AWS		~$22/mes

Beneficio: Escalado automatico sin costo adicional durante picos de demanda.

Cache Multi-Nivel

Tier 3

Sistema de cache de dos niveles para maximizar rendimiento y minimizar costos de API.

L1: Redis

In-Memory

Ultra rapido (sub-ms latency)

TTL de 7 dias automatico

Cache de traducciones y chunks

Estadisticas de hits/misses

L2: PostgreSQL

Persistente

Sin expiracion (permanente)

Fallback si Redis no disponible

Popula L1 automaticamente en miss

Metricas de ahorro en USD

Flujo de Cache

GET Translation:
┌─────────────┐     HIT     ┌─────────────────────────────────┐
│  Request    │ ──────────▶ │  Return from Redis (< 1ms)      │
└──────┬──────┘             └─────────────────────────────────┘
       │ MISS
       ▼
┌─────────────┐     HIT     ┌─────────────────────────────────┐
│  Check L2   │ ──────────▶ │  Return + Populate L1           │
│  PostgreSQL │             └─────────────────────────────────┘
└──────┬──────┘
       │ MISS
       ▼
┌─────────────────────────────────────────────────────────────┐
│  Call AI API → Store in L1 + L2 → Return                    │
└─────────────────────────────────────────────────────────────┘

Rate Limiting por Plan

Tier 3

Limites de peticiones usando sliding window algorithm con Redis para distribucion.

Plan	Por Minuto	Por Hora	Por Dia
FREE	5	20	50
PRO	30	200	500
BUSINESS	100	1,000	5,000
DEV / ADMIN	∞	∞	∞

Cuando se excede el limite, se retorna HTTP 429 con headers Retry-After y X-RateLimit-Reset.

Metricas de Calidad

Tier 3

Cada traduccion se evalua automaticamente en multiples dimensiones de calidad (0-100).

Consistencia

Uso correcto de terminos del glosario y nombres propios

Fluidez

Estructura de oraciones y naturalidad del texto

Precision

Fidelidad al significado del texto original

Escala de Calificaciones

A+95-100

A90-94

B80-89

C70-79

D60-69

F0-59

Se mide la mejora entre pases (pass1 → pass3) para validar efectividad del sistema de 3 pases.

Notificaciones en Tiempo Real

Tier 3

Server-Sent Events (SSE) para actualizaciones instantaneas sin polling.

Tipos de Eventos

Evento	Descripcion	Datos
translation_progress	Progreso de traduccion	bookId, chapterNumber, progress %
translation_complete	Traduccion terminada	bookId, duration, tokensUsed
translation_error	Error en traduccion	bookId, error message
notification	Notificacion general	id, type, title, message

Uso en React

import { useRealtime, useTranslationProgress } from "@/hooks/use-realtime";

// Hook general
const { isConnected, progress, notifications } = useRealtime();

// Hook para libro especifico
const { percentage, currentChapter, isComplete } = useTranslationProgress(bookId);

// Ejemplo de UI
{isConnected ? "🟢 Conectado" : "🔴 Desconectado"}
{progress && <ProgressBar value={progress.progress} />}

Auto-reconexion con backoff

Heartbeat cada 30 segundos

Redis pub/sub multi-instancia

Fallback in-memory si no hay Redis

Documentacion Relacionada

Enterprise Features

Micro-features de UX

Developer Keys

API keys personalizadas

Volver a Documentacion