Construir un CMS Headless personalizado para Astro (en lugar de pagar por uno)

Elegimos Astro como nuestro framework frontend por su rendimiento, experiencia de desarrollo y versatilidad. Pero un frontend rápido es solo la mitad de la ecuación. El contenido sigue necesitando un hogar. Nuestros clientes necesitan formas de actualizar páginas, publicar entradas de blog y gestionar su presencia digital. En lugar de cambiar una dependencia (WordPress) por otro CMS SaaS, construimos nuestro propio CMS headless personalizado desde cero. Lo que empezó como una herramienta interna sencilla para gestionar exhibiciones de diseño ha evolucionado hasta convertirse en una plataforma de gestión de contenido completa que alimenta todos nuestros sitios Astro de clientes.

¿Por qué no Sanity, Contentful o Strapi?

El problema más inmediato con las plataformas CMS SaaS comerciales es el precio. Sanity cobra $99 por usuario por mes. Contentful empieza en $300 por mes para planes básicos. Cuando gestionas más de 10 sitios de clientes con múltiples editores cada uno, las cuentas no cuadran. Dos editores por sitio en 10 sitios significan 20 usuarios. A $99 por usuario, eso representa casi $2,000 por mes, o $24,000 al año, solo por acceso a la gestión de contenido.

Más allá del costo, la dependencia del proveedor es un riesgo estratégico real. Tu contenido vive en la infraestructura de otra empresa, en su formato propietario. Si cambian los precios, eliminan funciones o cierran operaciones, te toca correr a migrar. Hemos visto esto ocurrir con otras herramientas SaaS, y preferimos ser dueños de nuestros datos y nuestra infraestructura.

Strapi, la opción de código abierto auto-alojada, elimina las tarifas por usuario pero trae su propia carga de mantenimiento como una aplicación Node.js de gran tamaño. Su modelado de contenido es flexible pero tiene opiniones fuertes que no siempre encajaron con nuestros proyectos. Queríamos control total sobre la API de contenido, la experiencia de edición y la estructura de datos.

Lo que construimos

El backend usa FastAPI, un framework web de Python de alto rendimiento, con SQLAlchemy como ORM y MariaDB para el almacenamiento. FastAPI nos da endpoints de API rápidos y bien documentados con soporte asíncrono incorporado. La interfaz de administración usa Tailwind CSS para los estilos y Alpine.js para interactividad ligera, creando un panel responsivo sin la sobrecarga de un framework JavaScript pesado.

El esquema de la base de datos abarca 16 tablas que cubren todo el alcance de la gestión de contenido: usuarios, sitios, páginas, historial de ediciones, bloqueos de contenido, plantillas base, claves de API, traducciones de páginas, formularios, envíos de formularios, registros de actividad, variantes de imágenes, registros de generación y plantillas de contenido. Esta estructura soporta operación multi-tenant en todos nuestros sitios de clientes desde una sola instalación.

Las funcionalidades principales incluyen:

• API JSON headless en /api/v1/ con autenticación por clave de API para acceso seguro al contenido desde el exterior.
• Soporte multilenguaje con generación automática de sitemaps con hreflang para SEO internacional.
• Plantillas base (Blueprints) para plantillas de contenido estructurado que garantizan consistencia entre tipos de contenido.
• Publicación programada con un ejecutor de tareas en segundo plano para liberación automática de contenido.
• Bloqueo pesimista de contenido con expiración de 15 minutos y actualización por heartbeat para prevenir conflictos de edición.
• Transformaciones de imágenes vía Pillow: variantes automáticas de miniatura, pequeña, mediana y grande, más conversión a WebP.
• Registros de auditoría de actividad para rastrear cada acción en la plataforma.

El editor con IA

Esto es lo que distingue a nuestro CMS de todo lo demás en el mercado. Claude Sonnet impulsa una experiencia de edición basada en chat que cambia fundamentalmente la forma en que los usuarios no técnicos interactúan con el contenido de su sitio web.

Así funciona: un cliente abre una página en el CMS e inicia un chat. Describe lo que quiere cambiar en lenguaje natural. "Haz que la sección principal sea más prominente y agrega un botón de llamada a la acción." "Reescribe este párrafo para que sea más conciso." "Agrega una sección de testimonios debajo de la descripción de servicios." Claude Sonnet procesa la instrucción, entiende el contexto del HTML existente y edita el markup directamente.

Una vista previa en vivo se muestra junto al chat. Los clientes ven los cambios en tiempo real y pueden iterar con instrucciones adicionales hasta que el contenido coincida con su visión. Sin complejidad de editores WYSIWYG, sin curva de aprendizaje de arrastrar y soltar, sin necesidad de conocimientos de HTML.

Claude Haiku se encarga de los resúmenes automáticos de revisiones. Cada vez que se guarda, se genera una descripción legible de lo que cambió: "Se revisó el titular principal para mayor claridad y se agregó una llamada a la acción" en lugar de un genérico "Página actualizada". Esto hace que el historial de ediciones sea realmente útil para rastrear la evolución del contenido y simplificar las reversiones.

Cómo se conecta Astro

Diseñamos dos patrones de integración para conectar los frontends de Astro con el CMS.

Patrón 1: Consultas directas a la base de datos. Para sitios alojados en el mismo servidor, las páginas SSR de Astro consultan las tablas de MariaDB del CMS directamente usando un pool de conexiones mysql2. Una página de listado de blog llama a getBlogPosts() que ejecuta un SELECT contra la tabla blog_posts. Una ruta dinámica de caso de estudio llama a getCaseStudy(slug). Este enfoque es simple y rápido, sin sobrecarga HTTP. Usamos este patrón en Med-Vision, un sitio de consultoría de salud construido con Astro 4 SSR.

Patrón 2: API JSON headless. Para configuraciones distribuidas o generación de sitios estáticos, Astro hace solicitudes fetch autenticadas a los endpoints /api/v1/ durante el proceso de build. La API devuelve JSON estructurado que Astro usa para generar archivos HTML estáticos. Este patrón funciona para cualquier frontend, no solo Astro, y soporta cacheo agresivo.

Ambos patrones se usan activamente en nuestros sitios de clientes. La conexión directa a la base de datos es más simple para implementaciones co-ubicadas. La API ofrece flexibilidad para arquitecturas distribuidas. Este enfoque dual se conecta naturalmente con nuestro flujo de migración desde WordPress y aprovecha todas las capacidades del framework Astro.

Gestión de sitios por SSH/SFTP

El CMS también funciona como administrador remoto de sitios. Usando Paramiko, una librería SSH de Python, se conecta a los servidores de producción de los clientes para gestión directa de archivos. Los usuarios pueden explorar el árbol de archivos remoto, editar archivos desde el navegador, subir recursos y gestionar permisos, todo desde el panel del CMS.

Esto es particularmente valioso durante nuestras conversiones de sitios estáticos. Cuando se migra un sitio legado de más de 100 páginas a Astro, hay numerosos archivos estáticos, archivos de configuración y redirecciones que necesitan gestión entre servidores. El CMS centraliza este trabajo junto con la gestión de contenido, eliminando la necesidad de clientes SFTP separados o sesiones de terminal para operaciones rutinarias con archivos.

La decisión de construir vs. comprar

Construir un CMS desde cero requiere un esfuerzo de ingeniería significativo. La versión inicial tomó semanas de desarrollo dedicado, y seguimos iterando sobre funcionalidades y rendimiento. No es un proyecto de fin de semana.

Pero para una empresa que gestiona más de 10 sitios de clientes, la economía es clara:

Más allá del costo, tienes control completo sobre las funcionalidades y la hoja de ruta. El editor con IA es algo que ningún CMS genérico ofrece con este nivel de integración. El CMS se adapta a nuestro flujo de trabajo, no al revés.

Nuestra recomendación: si gestionas 1 o 2 sitios, compra un CMS SaaS. La inversión en desarrollo no justifica el ahorro. Si gestionas más de 10 sitios con la capacidad de desarrollo para construir y mantener una solución personalizada, la inversión se paga sola rápidamente tanto en ahorro directo como en flexibilidad estratégica.