Plataforma de documentação — arquitetura e operação¶

Este documento é sobre o site de documentação (docs.garantora.com.br) — o que ele é, como rodar, validar e publicar. Para o deploy do produto, ver deployment.md.

Arquitetura da solução¶

Markdown puro em docs/ → Material for MkDocs gera um site estático (site/, artefato — nunca versionado) → servido por nginx num container próprio (docs) → exposto direto pelo nginx nativo do host (systemd + certbot, fora deste repositório) — não há Caddy nesta stack (migração db/redis/mailpit para serviços nativos, que também aposentou o Caddy interno do dev-remote em favor do roteamento por path no próprio nginx do host).

flowchart LR
    Docs["docs/*.md\n+ mkdocs.yml"] -->|"mkdocs build --strict"| Site["site/\n(artefato estático)"]
    Site -->|"COPY (no build da imagem)"| Nginx["container docs\nnginx:alpine\n127.0.0.1:8082"]
    Nginx -->|"proxy_pass :8082"| HostNginx["nginx do HOST\n(fora do git) + certbot"]
    HostNginx --> Internet(("docs.garantora.com.br"))

Mesmo padrão do web (build em duas etapas — Node/Python gera o artefato, nginx serve), mesma rede Docker (garantora-devremote_default) — nenhum proxy público novo dentro do Docker, nenhum segundo gerenciador de dependências (requirements-docs.txt é pip, como a própria API já usa por baixo do uv). O nginx do host é compartilhado com outra stack (advfl) que já divide a VPS — ver infra/dev-remote/README.md, "Topologia".

O site é aberto, sem senha: até 2026-10-15 o server do nginx do host exigia Basic Auth (auth_basic com um .htpasswd em formato apr1), e ela foi retirada — a documentação passou a ser lida sem credencial.

Por que dev-remote, e não produção. Até 2026-08-30 este site vivia em infra/prd (a mesma migração que o criou), e cada atualização de Markdown só ficava visível depois de um deploy de produção — o que não é o objetivo de um site de documentação em desenvolvimento ativo. O tweak "docs fora de produção" moveu tudo para infra/dev-remote: agora publicar a documentação é reconstruir o container docs do dev-remote (ver "Como publicar" abaixo). Produção não serve mais docs.garantora.com.br em nenhuma forma.

Como rodar localmente¶

python3 -m venv .venv-docs && source .venv-docs/bin/activate
pip install -r requirements-docs.txt
mkdocs serve       # http://127.0.0.1:8000, hot reload

mkdocs serve não passa pelo nginx do host — é só para escrever e revisar antes de publicar.

Como criar uma especificação, fix ou ADR¶

Desde 2026-10-15 não há skill próprio para escrever spec ou fix — os antigos /spec, /fix e /tweak foram removidos, e o trabalho é conduzido pelo plugin Superpowers. A fonte de como cada tipo de trabalho anda, e de onde ele grava, é a seção Fluxo de desenvolvimento do CLAUDE.md da raiz; aqui fica só o que toca a documentação:

Specification (funcionalidade) — o brainstorming escreve em docs/specifications/NNNN-slug/specification.md, sobre o template ../doc-templates/specification.md; o plano do writing-plans vai ao lado, em plan.md. Não em docs/superpowers/, que é o padrão do plugin.
Fix (defeito) — docs/fixes/NNNN-slug.md, sobre o template ../doc-templates/fix.md; evidência e print em docs/fixes/assets/.
O número sai de bash scripts/proximo-numero-spec.sh ou bash scripts/proximo-numero-fix.sh — sequencial, nunca reutilizado.
Ajuste direto (ícone, palavra, espaçamento) — não gera documento: o registro é a mensagem de commit. A pasta ../tweaks/ é só histórico do tempo em que o /tweak escrevia ali, e não recebe arquivo novo.
ADR — copie ../doc-templates/adr.md para docs/decisions/ADR-NNNN-slug.md (próximo número sequencial) e adicione a linha na tabela de ../decisions/index.md.

Em todos os casos, adicione a entrada correspondente em ../metadata/catalog.yaml, no mesmo formato das existentes, e a linha na tabela do índice da pasta (specifications/index.md, fixes/index.md). Ninguém faz isso automaticamente: sem a entrada, o documento só é alcançável por URL direta no site publicado. O roadmap.md, que até 2026-10-15 vivia como ROADMAP.md na raiz do repositório, agora está em docs/ e é publicado com o resto.

Como gerar o site¶

mkdocs build --strict

--strict transforma todo aviso (link quebrado, referência de nav ausente, âncora inexistente) em falha — é a validação principal desta plataforma. O resultado vai para site/ (artefato, .gitignore, nunca commitado).

Como validar¶

mkdocs build --strict        # links, nav, âncoras — falha se qualquer um estiver errado
python3 scripts/docs_lint.py # front matter, IDs duplicados, catálogo consistente com os arquivos

scripts/docs_lint.py cobre o que o mkdocs build não cobre: YAML de front matter válido, id único no repositório inteiro, type/status dentro da lista controlada (../metadata/README.md), toda entrada do catálogo apontando para um arquivo que existe, e todo arquivo com front matter tendo entrada no catálogo.

Como publicar¶

O site faz parte da stack infra/dev-remote, não da de produção — não há passagem por /ship. Há dois caminhos, conforme de onde vem o conteúdo:

O que está no checkout do dev-remote — /devremote-rebuild docs (ou junto de outros serviços: /devremote-rebuild web docs). Reconstrói a imagem docs a partir da árvore de trabalho do checkout principal e recria o container.
Uma branch de trabalho, para validar pela web antes do merge —

bash scripts/publicar-preview-docs.sh <branch>

Monta dois worktrees temporários — a infra de build (Dockerfile, nginx) sempre da main, o conteúdo (docs/, mkdocs.yml, requirements-docs.txt) da branch pedida —, roda mkdocs build --strict se houver .venv-docs no host (senão a validação acontece no build da imagem), reconstrói a imagem garantora-devremote-docs e recria só o container docs, sem mexer no HEAD do checkout principal nem em api/web. O site passa a servir aquela branch até a próxima publicação — ele é um só, compartilhado pelo time.

O que fica fora do repositório. Quem termina o TLS público e roteia por domínio é o nginx nativo do host (systemd + certbot) — não há Caddy nesta stack. docs.garantora.com.br é um server próprio, apontando para o container docs publicado em 127.0.0.1:8082 (ver infra/dev-remote/README.md, "Topologia" e "Provisionamento"):

DNS — A record de docs.garantora.com.br → 145.223.94.55 (já feito).
server do nginx do host — /etc/nginx/sites-available/docs.garantora.com.br, com o certificado emitido pelo certbot; um proxy_pass para 127.0.0.1:8082, sem auth_basic.

Como atualizar¶

Editar o Markdown em docs/ (página nova entra também no nav do mkdocs.yml), rodar as validações acima e publicar por um dos dois caminhos de "Como publicar".

Como fazer backup¶

O site é derivado — site/ é reconstruído a partir de docs/ a cada build, e docs/ já está versionado no Git como o resto do repositório. Não há dado próprio a salvar (diferente do Postgres): o backup deste componente é o backup do repositório.

Como fazer rollback¶

git checkout <commit-anterior> -- docs/ mkdocs.yml requirements-docs.txt

Depois, /devremote-rebuild docs reconstrói a imagem docs com o conteúdo revertido (ou bash scripts/publicar-preview-docs.sh main, para voltar o site à main depois de uma prévia de branch). Não há "deploy inteiro" a reverter aqui — o site de documentação não é mais parte da stack de produção (ver deployment.md para o rollback do produto, que é independente).

Como diagnosticar erros¶

Sintoma	Causa provável	Onde olhar
`mkdocs build --strict` falha	link relativo quebrado, arquivo referenciado no `nav` sem existir, ou front matter YAML inválido	a própria mensagem de erro cita arquivo e linha
Site sobe mas página em branco/404	`docs_dir`/`nav` desalinhado com a árvore real, ou build falhou silenciosamente antes do `COPY` no `docs.Dockerfile`	`docker compose logs docs`, e rodar `mkdocs build --strict` local primeiro
`docs.garantora.com.br` não responde	DNS não apontado, `server` do nginx do host ausente/errado, ou certificado ainda não emitido	na VPS: `nginx -t`, `systemctl status nginx`, `certbot certificates` — depois `docker compose logs docs` para o container em si
401 ao abrir o site	o `server` do nginx do host ainda tem `auth_basic` — o site não tem mais senha desde 2026-10-15	na VPS: `/etc/nginx/sites-available/docs.garantora.com.br`, depois `nginx -t` e `systemctl reload nginx`
O site mostra conteúdo de outra branch	a última publicação foi uma prévia (`publicar-preview-docs.sh <branch>`)	republicar a `main` (ver "Como fazer rollback")
Mermaid não renderiza	sintaxe do bloco `mermaid` errada, ou `pymdownx.superfences` sem o `custom_fences` do `mkdocs.yml`	inspecionar o console do navegador; conferir `mkdocs.yml`

Como a IA deve consumir esta documentação¶

Ver ../ai-guide.md — não duplicado aqui.