Arquitectura

Chinaski se divide deliberadamente en unas pocas piezas pequeñas en movimiento en lugar de un gran servidor siempre encendido. Esta página explica las cuatro piezas (la aplicación admin, el builder, la salida estática y el manager) y cómo se relacionan, para que el resto de la documentación tenga un punto de apoyo.

La aplicación admin

La aplicación admin (cms.pl) es el proceso con el que interactúas: sirve la interfaz de administración basada en navegador y la API REST. Todo lo que haces como usuario ocurre aquí: escribir y editar contenido, gestionar usuarios y formularios, configurar ajustes, gestionar claves de API y respaldos, y ver los registros de traducción y eventos.

Contiene una base de datos SQLite con todo, desde el contenido de las páginas hasta el historial de auditoría, y corre únicamente en tu servidor, enlazada a una dirección de loopback detrás de tu proxy inverso, nunca directamente accesible para los visitantes. Es un programa único y autosuficiente (un archivo Perl más sus módulos de librería), desplegable de tres maneras: como servicio de systemd en producción, como servidor de desarrollo mientras programas, o como servidor independiente para despliegues sin conexión.

También expone los endpoints de API que consumen las herramientas (estado de build, trabajos por lotes, cobertura de traducción, ajustes y la especificación OpenAPI), para que herramientas externas (incluyendo asistentes de IA mediante el servidor MCP incluido) puedan manejar el CMS sin tocar la interfaz de navegador.

El builder

El builder es un programa aparte que convierte el contenido de la base de datos en el sitio publicado. Lee la misma base de datos, renderiza cada página y post a través de las plantillas una vez por idioma configurado, y escribe archivos planos al disco. Nada del builder está oculto: cada build es una operación que tú o un webhook disparan explícitamente, registra sus fases, guarda verificaciones de calidad y resultados, y almacena un historial completo de cada ejecución, con progreso en vivo visible en el dashboard del admin mientras corre.

El builder escribe más que páginas: cada build regenera el sitemap, el feed RSS, el robots.txt, el archivo de política de seguridad y los archivos de redirección de cada idioma: la salida publicada completa del sitio, determinística a partir del contenido actual de la base de datos.

Salida estática

El builder escribe el sitio al disco como directorios de HTML plano por idioma, además de los archivos auxiliares mencionados. Tu servidor web de preferencia (las configuraciones de Caddy o nginx se incluyen con el proyecto) sirve esos archivos directamente a los lectores.

Esta separación es la decisión arquitectónica central: los lectores nunca tocan el CMS. El sitio publicado funciona tanto si la aplicación admin está corriendo como si no; incluso si todo el CMS estuviera fuera de línea, el sitio sigue en pie. Las únicas solicitudes de lectores que llegan a la aplicación admin son los envíos de formularios (los formularios se capturan en vivo por el CMS) y las sondas de escáner dirigidas deliberadamente a URLs honeypot. El caché en la capa del proxy significa que el contenido reconstruido llega a los lectores en cuestión de minutos.

El manager

La documentación también nombra un manager: un panel de control para aprovisionar y ejecutar muchos sitios desde un solo lugar. Existe como producto propio, Chinaski Manager (github.com/bigjohncobb/chinaski-manager), y se empareja con el CMS en un único servidor que corre muchas instancias.

Lo que hace el Manager:

Tenants e instancias. Crea tenants, luego bajo cada tenant aprovisiona nuevas instancias Chinaski (por defecto desde el repositorio upstream), y ejecuta su ciclo de vida completo: build, deploy, rollback a una versión anterior, iniciar/detener, reiniciar y eliminar. Los despliegues corren por etapas (descarga de código, dependencias, build, reinicio); si una etapa falla, el manager lo recuerda y puede reintentar desde esa etapa en lugar de empezar de cero.
Discovery. Un servidor existente puede escanearse en busca de instancias Chinaski que el Manager aún no conoce: busca las unidades de systemd y las señales de escucha-y-trabaja-en-el-directorio-correcto, clasifica qué puede importarse y permite a un superadmin importar las instancias encontradas en un solo paso.
Dominios. Adjunta dominios de admin y públicos a cualquier instancia, y la configuración de Caddy se regenera y recarga automáticamente; cada instancia conserva su propio puerto para que los upstreams sigan siendo únicos.
Respaldos. Snapshots de base de datos por instancia creados con el comando de snapshot seguro del propio SQLite, con restauración (que limpia los archivos shadow de la base de datos para que abra limpiamente), además de respaldo y restauración separados de la base de datos del propio panel de control del Manager.
Verificaciones de salud. Monitoreo de instancias en segundo plano (por defecto: cada minuto), con alertas por webhook opcionales y alertas por correo por instancia. El propio Manager expone un endpoint de salud para monitores externos y se reinicia automáticamente bajo systemd si falla.
Personas y tokens. Tres roles con alcance por tenant: superadmin (todo, incluida la gestión de tenants/usuarios y discovery), admin (las instancias de un tenant) y user (sus propios tokens de API más una vista del audit log de su tenant). Los tokens de API vienen en versiones de solo lectura o de acceso completo, y hay un pequeño cliente de línea de comandos para ambos.
Rendición de cuentas. Cada acción a nivel de manager se registra en un audit log con quién, qué y en qué tenant.

El Manager mantiene su propia base de datos y su propio secreto, separados: es una aplicación de plano de control, no algo que viva dentro de tus instancias del CMS.

Distinción importante: el Manager controla muchas instancias del CMS single-tenant (una base de datos SQLite por sitio). El "CMS multi-tenant con Postgres" del roadmap del proyecto principal es algo distinto y sin entregar: un solo CMS sirviendo a muchos tenants. Multi-sitio hoy = muchas instancias, ya sea que las gestiones a mano con los patrones de systemd incluidos o a través del Manager.

Lo que existe hoy en el proyecto principal es exactamente lo que importa la función Discovery: servicios de systemd de instancia única donde un patrón de unidad ejecuta cualquier cantidad de sitios (chinaski@1, chinaski@prod, chinaski@staging…), cada uno con su propia base de datos, directorio de salida, archivo de secretos y respaldos.

El otro daemon incluido: el servidor MCP

Un componente más incluido, y el tercer proceso que quizá realmente ejecutes: chinaski-mcp, un adaptador que permite a los asistentes de IA (Claude Code y cualquier cliente compatible con MCP) operar el CMS a través de la API. Habla JSON-RPC sobre stdio, expone las herramientas de CRUD/traducción/operaciones masivas de contenido, mantiene su propio almacén de sesiones y corre como su propio servicio de systemd cuando se despliega. No es el manager descrito arriba; es un controlador para una sola instancia del CMS. Se incluye porque este código se desarrolla AI-first, pero es una herramienta opcional: sin ella, el CMS funciona de manera idéntica a través del navegador.

Cómo fluye una solicitud

Solicitud de lector: servidor web → archivo estático en disco → listo. El CMS no interviene.
Envío de formulario: servidor web → /forms/<slug> redirigido por proxy inverso → aplicación admin → base de datos (+ notificación/webhooks).
Edición de contenido: admin con sesión iniciada → aplicación admin → base de datos (con revisiones y auditoría registradas) → rebuild explícito → archivos estáticos actualizados → los lectores ven el contenido fresco dentro de la corta ventana de caché del proxy.
Operaciones de flota: Manager → unidades de systemd, puertos y dominios de las instancias → instancias del CMS aprovisionadas/compiladas/desplegadas por tenant, con salud y respaldos supervisados centralmente.

El resumen en una línea

Cuatro piezas: la aplicación admin donde editas, el builder que publica, los archivos estáticos que sirven, y el Manager, que une muchos de esos sitios desde un solo panel.