Arquitetura

O Chinaski é deliberadamente dividido em algumas peças pequenas em movimento, em vez de um grande servidor sempre ligado. Esta página explica as quatro peças. A aplicação de administração, o builder, a saída estática e o manager. E como elas se relacionam, para que o resto da documentação tenha um lugar de apoio.

A aplicação de administração

A aplicação de administração (cms.pl) é o processo com o qual você interage: ela serve a interface de administração baseada em navegador e a API REST. Tudo o que você faz como usuário acontece aqui. Escrever e editar conteúdo, gerenciar usuários e formulários, configurar opções, gerenciar chaves de API e backups, e acompanhar os logs de tradução e eventos.

Ela mantém um banco de dados SQLite contendo tudo, do conteúdo de páginas ao histórico de auditoria, e roda apenas no seu servidor. Vinculada a um endereço de loopback atrás do seu reverse proxy, nunca diretamente acessível aos visitantes. É um programa único e autocontido (um arquivo Perl mais seus módulos de biblioteca), implantável de três formas: um serviço systemd em produção, um servidor de desenvolvimento enquanto você desenvolve, ou um servidor standalone para implantações offline.

Ela também expõe os endpoints de API que o ferramental consome. Status de build, jobs em lote, cobertura de tradução, configurações e a especificação OpenAPI. Para que ferramentas externas (incluindo assistentes de IA por meio do servidor MCP empacotado) possam comandar o CMS sem tocar na interface de navegador.

O builder

O builder é um programa separado que transforma o conteúdo do banco de dados no site publicado. Ele lê o mesmo banco de dados, renderiza cada página e post por meio dos templates uma vez por idioma configurado e escreve arquivos puros em disco. Nada no builder é escondido: cada build é uma operação que você ou um webhook dispara explicitamente, ele registra suas fases, grava verificações de qualidade e resultados, e armazena um histórico completo de cada execução. Com progresso ao vivo visível no dashboard de administração enquanto roda.

O builder escreve mais do que páginas: cada build regenera o sitemap, o feed RSS, o robots.txt, o arquivo de política de segurança e os arquivos de redirecionamento de cada idioma. A saída publicada completa do site, determinística a partir do conteúdo atual do banco de dados.

Saída estática

O builder escreve o site em disco como diretórios de HTML puro por idioma, mais os arquivos auxiliares acima. Seu servidor web de escolha (configurações de Caddy ou nginx acompanham o projeto) serve esses arquivos diretamente aos leitores.

Essa divisão é a decisão arquitetural central: os leitores nunca tocam no CMS. O site publicado funciona quer a aplicação de administração esteja rodando ou não. Mesmo que o CMS inteiro estivesse offline, o site continua no ar. As únicas requisições de leitores que chegam à aplicação de administração são envios de formulários (formulários são capturados ao vivo pelo CMS) e sondas de scanners deliberadamente roteadas para URLs honeypot. O cache na camada de proxy significa que o conteúdo reconstruído chega aos leitores em minutos.

O manager

A documentação também cita um manager: um painel de controle para provisionar e rodar muitos sites de um só lugar. Ele existe como seu próprio produto. Chinaski Manager (github.com/bigjohncobb/chinaski-manager). E faz par com o CMS em um único servidor rodando muitas instâncias.

O que o Manager faz:

Tenants e instâncias. Crie tenants e, sob cada tenant, provisione novas instâncias do Chinaski (por padrão, a partir do repositório upstream), e execute o ciclo de vida completo delas: build, deploy, rollback para uma versão anterior, start/stop, restart e remoção. Os deployments rodam em estágios (busca de código, dependências, build, restart). Se um estágio falha, o manager lembra e pode tentar novamente daquele estágio em vez de começar do zero.
Discovery. Um servidor existente pode ser escaneado em busca de instâncias do Chinaski que o Manager ainda não conhece: ele procura as units do systemd e os sinais de escuta-e-trabalha-no-diretório-certo, classifica o que pode ser importado e permite que um superadmin importe as instâncias encontradas em um passo.
Domínios. Anexe domínios de admin e públicos a qualquer instância, e a configuração do Caddy é regenerada e recarregada automaticamente. Cada instância mantém sua própria porta para que os upstreams permaneçam únicos.
Backups. Snapshots de banco de dados por instância construídos com o próprio comando de snapshot seguro do SQLite, com restauração (que limpa os arquivos de sombra do banco de dados para que ele abra de forma limpa), além de backup e restauração separados do próprio banco de dados do painel de controle do Manager.
Verificações de saúde. Monitoramento em segundo plano das instâncias (padrão: a cada minuto), com alertas opcionais por webhook e alertas por e-mail por instância. O próprio Manager expõe um endpoint de saúde para monitores externos e se autorreinicia sob systemd se travar.
Pessoas e tokens. Três papéis com escopo por tenant. Superadmin (tudo, incluindo gestão de tenants/usuários e discovery), admin (as instâncias de um tenant) e user (seus próprios tokens de API mais uma visão do log de auditoria de seu tenant). Tokens de API vêm em versões somente leitura ou de acesso total, e há um pequeno cliente de linha de comando para ambos.
Responsabilização. Toda ação no nível do manager é registrada em um log de auditoria com quem, o quê e qual tenant.

O Manager mantém seu próprio banco de dados e segredo separados. É uma aplicação de control-plane, não algo que vive dentro das suas instâncias do CMS.

Distinção importante: o Manager controla muitas instâncias do CMS *single-tenant* (um banco de dados SQLite por site). O "CMS multi-tenant com Postgres" no roadmap do projeto principal é uma coisa diferente e não entregue: um CMS servindo muitos tenants. Multi-site hoje = muitas instâncias, seja gerenciando-as à mão com os padrões de systemd distribuídos ou por meio do Manager.

O que existe no projeto principal hoje é exatamente o que o recurso Discovery importa: serviços systemd de instância única em que um padrão de unit roda qualquer número de sites (chinaski@1, chinaski@prod, chinaski@staging…), cada um com seu próprio banco de dados, diretório de saída, arquivo de segredo e backups.

O outro daemon distribuído: o servidor MCP

Mais um componente distribuído. E o terceiro processo que você pode realmente rodar: chinaski-mcp, um adaptador que permite que assistentes de IA (Claude Code e qualquer cliente compatível com MCP) operem o CMS por meio da API. Ele fala JSON-RPC sobre stdio, expõe as ferramentas de CRUD de conteúdo/tradução/operações em massa, mantém seu próprio armazenamento de sessões e roda como seu próprio serviço systemd quando implantado. Ele não é o manager descrito acima: é um driver para uma única instância do CMS. Ele é distribuído porque esta base de código é desenvolvida AI-first, mas é uma ferramenta opcional: sem ele, o CMS funciona de forma idêntica pelo navegador.

Como uma requisição flui

Requisição de leitor: servidor web → arquivo estático em disco → feito. O CMS não está envolvido.
Envio de formulário: servidor web → /forms/<slug> com proxy reverso → aplicação de administração → banco de dados (+ notificação/webhooks).
Edição de conteúdo: admin autenticado → aplicação de administração → banco de dados (com revisões e auditoria registradas) → rebuild explícito → arquivos estáticos atualizados → leitores veem o conteúdo fresco dentro da curta janela de cache do proxy.
Operações de frota: Manager → units do systemd das instâncias, portas e domínios → instâncias do CMS provisionadas/construídas/implantadas por tenant, com saúde e backups acompanhados centralmente.

O resumo de uma linha

Quatro peças: a aplicação de administração em que você edita, o builder que publica, os arquivos estáticos que servem. E o Manager, que amarra muitos desses sites a partir de um único painel.