Glossário

Vocabulário da plataforma de documentação da X-Adm — os termos que aparecem na constituição, nos templates e na infraestrutura do site.

Termos de negócio de cada aplicação (transporte, combustíveis, fiscal…) vivem no docs/glossario.md do repositório da própria aplicação — cada glossário define o vocabulário do seu repo; não duplicar, linkar.

O padrão de documentação

Constituição

O documento que define o que documentamos, para quem e qual o mínimo (padroes/constituicao.md). Tudo deriva dela; em conflito, ela vence.

Docs as Code

Abordagem em que a documentação é tratada como código: Markdown versionado no Git, revisado em PR e publicado por pipeline automático. HTML e Word são saídas geradas — nunca editadas à mão.

Design doc

Documento de projeto (nível 2): contexto, escopo, modelo de dados, fluxos, decisões e riscos de uma feature/projeto. Vive em docs/design/ do repo do app. Template.

RD — Registro de Decisão

Registro de ~1 página de uma decisão técnica: contexto, decisão, consequências, alternativas. Append-only: RD aceito não se reescreve — é superado por outro (superado-por: NNNN). Vive em docs/rd/.

Guia de usuário

Documento do nível 4: passo a passo com screenshots para usuário final e suporte, sem jargão técnico. Vive em docs/guias/.

Frontmatter

Bloco YAML no início de cada .md (entre ---) com os metadados obrigatórios: titulo, tipo, status, responsavel, modulo etc. Definido na constituição.

Slug

O nome do arquivo .md, que vira a URL pública da página. É um ID estável: não se renomeia sem redirect (quebra busca, links e o futuro RAG).

Migração oportunista

Política para doc legada: não se migra por migrar — só o que está sendo tocado. Projeto novo já nasce no padrão.

Ferramentas da plataforma

MkDocs (Material)

Gerador de site estático que transforma os .md neste site. Material é o tema usado (busca em pt-BR, navegação). Cada app tem seu próprio mkdocs.yml.

Mermaid

Linguagem de diagramas em texto, embutida nos .md (blocos ```mermaid). Renderiza no site; no Git fica só a fonte, nunca o SVG/PNG.

Javadoc / dartdoc

Geradores de API reference a partir dos comentários no código Java e Flutter/Dart. Rodam no CI de cada app; a saída entra no site do app em api/.

Forgejo

A forja Git da X-Adm: repositórios, issues, pull requests e CI (Forgejo Actions). Não-devs editam Markdown pela interface web dele. Mais.

Coolify

PaaS self-hosted que builda e deploya os containers — inclusive este site. Mais.

Traefik

Proxy reverso do Coolify: termina o HTTPS (Let's Encrypt) na borda e encaminha para os containers. Mais.

Garage

Object storage S3-compatível da X-Adm. Na plataforma de docs, é o ponto de troca: cada app publica seu site no bucket docs-sites e este site sincroniza de lá (como funciona). Mais.