Plataforma y Operacion

Manual vivo de Aeternus: arquitectura, despliegue y continuidad operativa.

Este front consolida como funciona Aeternus, que migramos al core Python, cuales son los servicios activos en AWS y como resolver incidentes sin perder tiempo en diagnosticos dispersos.

Objetivo: que cualquier desarrollador nuevo pueda desplegar, observar, depurar y escalar el sistema sin depender de conocimiento tribal del equipo.

Next.js + FastAPIECS FargateNeo4j + PostgreSQLOpenAI + ElevenLabs

Arquitectura de alto nivel

Frontend

Next.js 14 + TypeScript + Tailwind

Interfaz web, experiencias de chat y paneles administrativos. Mantiene rutas API de compatibilidad para no romper clientes mientras se migra al core.

Core API

FastAPI + Uvicorn + Python 3.12

Orquesta chat, TTS, rasgos afectivos, estado Neo4j y persistencia de sesiones/mensajes. Es el backend canonicamente escalable en ECS Fargate.

Datos

PostgreSQL + Neo4j Aura

PostgreSQL almacena conversaciones y sesiones. Neo4j modela relaciones, rasgos y dinamica afectiva para continuidad narrativa.

Modelos

OpenAI + ElevenLabs

OpenAI responde con contexto conversacional completo. ElevenLabs sintetiza voz y usa reintentos controlados cuando hay limites de concurrencia.

Flujo real de una request

Este flujo describe lo que ocurre desde que un usuario envia un mensaje hasta que Aeternus responde con texto o audio. Es la referencia principal para depurar regresiones funcionales.

1. Entrada del usuario

El usuario escribe en la UI de Next.js. Si NEXT_PUBLIC_CORE_API_BASE_URL esta definido, las llamadas migradas se enrutan al core en AWS.

2. Contexto conversacional

El route de chat en Next.js arma el historial completo (incluyendo system-init) y lo delega al core para evitar respuestas genericas.

3. Enriquecimiento afectivo

El core consulta Neo4j para rasgos y relacion, y aplica reglas de estado para modular tono, humor y cercania de la respuesta.

4. Generacion y persistencia

El core responde con OpenAI, y luego persiste eventos/mensajes en PostgreSQL para continuidad entre sesiones.

5. Entrega final

La respuesta vuelve al cliente. Si se solicita audio, el core llama a ElevenLabs y entrega stream/audio listo para reproducir.

Inventario de servicios

Servicio	Nombre	Uso
ECR	aeternus-core	Repositorio de imagenes del core.
ECS Cluster	aeternus-core-cluster	Cluster Fargate para ejecucion del servicio.
ECS Service	aeternus-core-service	Replica activa del core; despliegues rolling.
Task Family	aeternus-core	Definicion versionada de contenedor y secretos.
CloudWatch Log Group	/ecs/aeternus-core	Logs runtime para debug y operacion.
Target Group	aeternus-core-tg	Health check en /v1/health (puerto 8080).
Load Balancer	aeternus-core-alb	Entrada publica HTTP/HTTPS al core.
Task SG	aeternus-core-task-sg	Permite 8080 solo desde ALB SG.

Endpoints ya migrados al core

POST /api/chat/saveMessage
POST /api/chat/loadMessages
POST /api/chat/deleteMessages
POST /api/chat/saveSession
GET/POST /api/tts
GET /api/ai/traits
GET /api/status/neo4j

Mapa de variables y secretos

Esta tabla evita configuraciones ambiguas entre Vercel, Next.js server y ECS. Si algo falla por entorno, empezar aqui suele ahorrar horas de debug.

Variable	Ambito	Proposito
NEXT_PUBLIC_CORE_API_BASE_URL	Vercel (frontend)	Rutea llamadas migradas al core publicado en AWS.
CORE_API_BASE_URL	Next.js server	Permite delegacion server-to-server para chat y compatibilidad.
OPENAI_API_KEY	Secrets Manager -> ECS Task	Autenticacion con OpenAI para respuestas de chat.
DATABASE_URL	Secrets Manager -> ECS Task	Conexion a PostgreSQL para sesiones y mensajes.
NEO4J_URI / USERNAME / PASSWORD	Secrets Manager -> ECS Task	Acceso al grafo afectivo y de relaciones.
ELEVENLABS_API_KEY / VOICE_ID / MODEL_ID	Secrets Manager -> ECS Task	Sintesis de voz en endpoints TTS.

Que hicimos

Optimizada carga de traits: ahora es lazy y evita llamadas innecesarias a Neo4j en inicios con historial.
Migracion de TTS, traits y status al core en Python, con routing por NEXT_PUBLIC_CORE_API_BASE_URL.
Delegacion de chat desde Next.js al core conservando contexto completo de mensajes (incluye system-init).
Correccion de bug de variables de entorno con comillas en Docker mediante normalizacion centralizada.
Automatizacion de build/push y deploy en AWS con scripts reproducibles.
Provision de ALB + target group + wiring de ECS service para trafico estable sin depender de IPs efimeras.

Conexion con frontend

En Vercel, define la variable de entorno para que los clientes web apunten al core desplegado.

NEXT_PUBLIC_CORE_API_BASE_URL=https://core.tudominio.com
CORE_API_BASE_URL=https://core.tudominio.com

Si quieres mantener compatibilidad gradual, deja el route de chat en Next.js y delega al core solo cuando la variable este definida.

Solucion de problemas

Cada caso incluye sintomas observables, causa probable, comandos de validacion y remediacion concreta. La idea es convertir incidentes repetitivos en procedimientos deterministas.

ServiceNotFoundException (UpdateService)

Sintoma: El deploy registra task definition nueva, pero falla al actualizar el servicio.

Causa probable: El servicio aun no existe en el cluster; update-service no crea recursos.

Validacion

aws ecs list-services --region $AWS_REGION --cluster $ECS_CLUSTER
Confirmar que aeternus-core-service no aparece en serviceArns.

Remediacion

Crear el service una sola vez (UI o CLI).
Volver a ejecutar deploy-ecs.sh para siguientes revisiones.

invalid ssm parameters: aeternus/core/...

Sintoma: Las tareas no arrancan y ECS reporta ResourceInitializationError.

Causa probable: ECS intenta resolver secretos como SSM parameters porque valueFrom no usa ARN valido de Secrets Manager.

Validacion

Revisar eventos de service: aws ecs describe-services ... --query events
Inspeccionar task definition y verificar valueFrom en containerDefinitions[].secrets[].

Remediacion

Usar ARNs de Secrets Manager en valueFrom.
Mantener deploy-ecs.sh actualizado (ya resuelve nombre->ARN automaticamente).

AccessDenied ssm:GetParameters

Sintoma: La tarea inicia y cae antes de levantar Uvicorn.

Causa probable: ecsTaskExecutionRole no tiene permisos para resolver secretos al bootstrap del contenedor.

Validacion

Leer eventos de ECS y buscar AccessDeniedException sobre ssm:GetParameters.
Verificar policies adjuntas al role ecsTaskExecutionRole.

Remediacion

Adjuntar AmazonSSMReadOnlyAccess.
Adjuntar permisos de lectura de secrets (minimo GetSecretValue).
Forzar nuevo deployment al terminar permisos.

CannotPullContainerError (platform 'linux/amd64')

Sintoma: ECS no puede descargar imagen aunque ECR exista y la tag sea correcta.

Causa probable: La imagen fue construida para arquitectura distinta a la de Fargate.

Validacion

Eventos de ECS muestran descriptor mismatch para linux/amd64.
Revisar comando build y confirmar flag --platform.

Remediacion

Build y push con DOCKER_PLATFORM=linux/amd64.
Ejecutar deploy-ecs.sh para registrar revision nueva.

Timeout al /v1/health

Sintoma: curl a la IP publica de tarea queda en timeout aunque el servicio parece running.

Causa probable: Security Group incorrecto o prueba contra IP vieja por rotacion de tasks en Fargate.

Validacion

Obtener task ARN actual y ENI activo.
Confirmar SG real del ENI (no asumir SG por nombre).
Probar health via ALB, no via IP efimera, cuando este disponible.

Remediacion

Permitir 8080 desde ALB SG hacia Task SG.
Evitar depender de IP directa; usar DNS de ALB para smoke tests.

AccessDenied iam:CreateServiceLinkedRole (ELB)

Sintoma: Falla la creacion del ALB aun con subnets y SG validos.

Causa probable: La cuenta no tiene creado AWSServiceRoleForElasticLoadBalancing.

Validacion

Error explicito de iam:CreateServiceLinkedRole en CLI.
Verificar existencia del role en IAM.

Remediacion

Crear service-linked role una sola vez con usuario admin.
Reintentar create-load-balancer.

Runbook operativo

Verificar salud global: ECS runningCount=1, pendingCount=0 y /v1/health respondiendo 200.
Si hay reinicios, leer eventos de service y ultimos streams de /ecs/aeternus-core.
Para nueva release: build-and-push.sh -> deploy-ecs.sh -> smoke test API -> smoke test chat web.
Mantener secretos en Secrets Manager y rotarlos sin tocar codigo.
Escalar con autoscaling por CPU/memoria y alarmas sobre 5xx o latencia.

Checklist de release

Antes de anunciar una release en produccion, ejecutar este checklist reduce el riesgo de rollback.

Confirmar branch limpia y revisar cambios de core y frontend.
Construir y publicar imagen con platform linux/amd64.
Actualizar ECS con deploy-ecs.sh y esperar estabilidad (running=1, pending=0).
Validar /v1/health via ALB y ejecutar prueba de chat extremo a extremo.
Monitorear 15-30 minutos: errores 5xx, reinicios de task y latencia de respuesta.