ADR-0001 · Payload CMS como fuente del contenido editorial, con Medusa como fuente del comercio

• Estado: aceptado
• Decisores: no registrado en el repositorio
• Fecha de la decisión: no registrada. La implementación aparece en el commit 8a8eced ("Se trabaja con paginas dinamicas de payload, formulario de dirección de envío...") y se consolida en 35cd3d8 ("menu de navegacion + algolia instantSearch").

Contexto y problema

El starter de Medusa trae la home y la navegación hardcodeadas en el código: cada cambio de banner, de bloque promocional o del menú de categorías exige tocar React, commitear y redesplegar. El negocio necesita cambiar ese contenido sin pasar por desarrollo. Medusa V2 administra productos, precios y regiones, pero no es un CMS de páginas.

Opciones consideradas

1. Payload CMS como servicio aparte, consumido por REST desde el storefront (elegida).
2. Seguir con contenido hardcodeado en componentes React.
3. Modelar el contenido editorial dentro de Medusa (metadata de colecciones, módulo propio).

No hay registro de que las opciones 2 y 3 se hayan evaluado formalmente; se listan como las alternativas que el código descarta de hecho.

Decisión

El contenido editorial —layout de la home y menú de navegación principal— se lee de Payload. El storefront se autentica con usuario y contraseña (PAYLOAD_USER_EMAIL / PAYLOAD_USER_PASSWORD), cachea el JWT en memoria del proceso y renderiza el contenido Lexical con src/lib/lexical-render.tsx. Las llamadas van desde el servidor (src/lib/payload.ts, src/lib/payload-home.ts) o desde route handlers que actúan de proxy (src/api/header/route.ts, src/app/api/credit-form/route.ts), nunca desde el navegador: las credenciales no salen del servidor.

Medusa sigue siendo la única fuente de verdad de catálogo, carrito y pedidos. Los bloques productGrid de la home guardan un filtro, y los productos concretos se resuelven contra Algolia en tiempo de render.

Consecuencias

Positivas

• Marketing edita la home y el menú sin deploy.
• La página se arma con Server Components: el contenido llega ya renderizado.
• Los proxies evitan exponer las credenciales de Payload al navegador.

Negativas / deuda asumida

• Una dependencia externa más en el camino crítico de la home. Si Payload no responde, la home muestra "No se encontró la homepage en Payload" (ver falla 4 del runbook).
• Autenticación por usuario y contraseña de servicio en vez de una API key: la rotación de esa contraseña exige reiniciar el proceso, porque el JWT se cachea en memoria.
• El caché del token vive en memoria del proceso: con varias réplicas, cada una hace su propio login.
• Tres orígenes de datos para una sola página (Payload, Algolia, Medusa) hacen más difícil explicar por qué la home se ve mal.