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 (documentacao/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.
Doc de projeto (etapa)¶
Documento de projeto (nível 2): contexto, escopo, modelo de dados, fluxos,
decisões e riscos de uma etapa da execução (docs/projeto/NN-titulo.md —
o delta daquele momento). Template.
Documentação Completa (o livro)¶
docs/projeto/index.md: o estado consolidado atual do sistema, autorado —
≠ das etapas, que são o retrato datado de cada entrega (decisão
0002). Embute a modelagem via
snippet e injeta o changelog no build.
Decisão (registro de decisão)¶
Registro de ~1 página de uma decisão técnica: contexto, decisão,
consequências, alternativas. Append-only: decisão aceita não se reescreve — é
superada por outra (superado-por: "NNNN", com aspas — sem elas o YAML lê
número/octal e o validador falha). Vive em docs/decisoes/.
Manual de usuário¶
Documento do nível 6: passo a passo com screenshots para usuário final e
suporte, sem jargão técnico. Vive em docs/public/manual/.
Andaime (.ia/)¶
Artefato de trabalho de uma feature (prompt/spec/plan das skills x-*), em
.ia/NNN-slug-*.md. Versionado mas não é doc: ao concluir, o durável é
destilado para docs/ e o andaime é apagado (Duas fontes da verdade — "feature
pronta = andaime apagável sem perda").
Manifesto (de templates)¶
manifesto.json no repo central: a única lista dos artefatos do kit (templates, scripts,
skills), com sha256, a versão do kit em que cada um mudou (mudou_em), os perfis e stacks a que
se aplica e o destino no repo, mais a lista do que o repo deve remover. É o que a /xadm-docs
usa para re-derivar o kit num repo (Versões).
Central de Apps¶
O plano de controle das funcionalidades compartilhadas (erros/GlitchTip,
arquivos/Garage, analytics/Aptabase+Metabase): o app declara o que usa no
docs/app.json (features) e a /xadm-setup provisiona e grava o
client-grade de volta (como funciona).
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¶
Dois sentidos, não confundir:
- Slug de página — 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). - Slug de app — o identificador público do app no
app.json(decisão 0024): pasta de docs (docs-sites/<slug>/), nome da imagem no registry (fonte.xadm.biz/xadm/<slug>) e raiz do nome do recurso Coolify (<slug>-[<instance>-]<target>-pull). É o mesmo valor doapp_ide do projeto de erro — uma identidade por app (decisão 0038, que substituiu a cláusula "pode divergir" da 0024; o validador barra a divergência). Renomear obriga a disciplina de rename (coolify).
Migração oportunista¶
Política para doc que ainda não segue o padrão: não se migra por migrar — só o que está sendo tocado. Projeto novo já nasce no padrão.
Vocabulário da casa¶
Termos que a norma usa com sentido próprio. Estão aqui porque não se deduzem do uso comum da palavra, e sem eles a leitura da norma trava.
Piso¶
O mínimo obrigatório de uma regra — abaixo dele não se entrega. Difere de meta: piso é o que a guarda cobra; acima dele, a escolha é do app.
Guarda¶
Verificação automática que cobra uma regra da norma (no CI, na skill ou num script da toolchain). Toda guarda cita a regra que implementa; regra sem guarda é convenção, não norma.
Gate¶
O conjunto de guardas que roda antes de deployar ou releasar. Gate vermelho não deploya; gate pulado também não.
Smoke¶
A verificação pós-deploy que confere se o que subiu responde o que devia: identidade do binário, rotas declaradas e ausência de erro novo. Deploy só encerra com smoke verde.
Corrente (estar na corrente)¶
Consumir a última versão publicada de cada lib da casa. Atrás da corrente é pendência declarada;
abaixo do piso da lib, a /xadm-release recusa.
Andaime¶
Documento de trabalho que sustenta a construção e não fica: spec, plano e prompt em .ia/. O que
é durável migra para docs/ no fechamento.
Carimbo¶
Valor gravado num artefato no momento da publicação para dizer de qual versão ele é — a versão da
norma no cabeçalho do validador, ou o mudou_em de cada entrada do manifesto.
Ponto de injeção (seam)¶
Lugar previsto no código para trocar uma dependência em teste (um override, um construtor que
aceita o cliente HTTP). Sem ele, testar exige subir a dependência real.
Desvio (drift)¶
Diferença que se acumula em silêncio entre duas coisas que deveriam ser iguais: o repo e o kit, a
prosa e o contrato, o catálogo e o app.json. É o que as guardas existem para pegar.
Rede de segurança (backstop)¶
Mecanismo lento que cobre a falha do mecanismo rápido — a varredura periódica que reconcilia o que o aviso direto não entregou. Nunca é o caminho principal.
Plataforma de Integração¶
Vocabulário da arquitetura de integração da casa; as definições completas vivem em Plataforma de Integração (norma na constituição, em Plataforma de Integração).
Tipo de fluxo¶
O formato do fluxo de dados (push X-Adm, batch de arquivo, entrada no ERP, push para API externa) — a unidade de organização da plataforma, no lugar do cliente. Detalhe.
Plataforma de Integração (serviço)¶
A cópia fiel do banco do X-Adm por cliente (int.<cliente>) + o connector do PowerSync; não é
porta de ingress de mais nada. O integrador, estreitado a este papel.
Detalhe.
App específico¶
Serviço específico que recebe de fora (relatório, webhook/poll), faz o específico do cliente e é
dono das suas tabelas; pode enviar dados para um terceiro ou para o X-Adm. Um por cliente.
Ex.: excel.<cliente>, pied.<cliente>.
Detalhe.
App compartilhado¶
App específico multi-tenant — 1 instância, N clientes — que nasce quando o parceiro é global
(mesmo endpoint para todos os clientes, cada um com sua credencial). Não escreve no barramento
diretamente: conversa com a Plataforma de Integração, que grava. Ex.: sascar.xadm.biz.
Detalhe ·
decisão 0018.
Barramento¶
O Postgres por cliente — onde todas as peças daquele cliente escrevem (owner-writes) e leem. É o ponto de integração, no lugar de um dispatcher na Plataforma de Integração. Detalhe.
Owner-writes¶
Invariante de que cada tabela tem um dono (roda o Flyway e escreve); os demais leem via PowerSync. Plataforma de Integração = réplica; app específico = suas tabelas (+ tabela de status quando envia para fora). Detalhe.
At-least-once¶
Garantia de entrega em que o evento chega pelo menos uma vez (nunca zero), podendo repetir —
o contrato do transporte M2M da casa (xadm-mensageria, outbox + relay sem dedup). A contrapartida
obrigatória é o receptor idempotente por chave natural: aplicar o mesmo evento N vezes = aplicar 1
vez. Decisão 0021 ·
3 mecanismos.
e2e-local¶
Suíte de teste ponta a ponta local e 100% automatizada de um fluxo de integração
multi-app (e2e-<cliente>-<fluxo>, ex.: e2e-maxsul-pied): sobe os apps de verdade
(build local, carimbado por commit; fake só nas bordas), dirige o fluxo e verifica que
não deu erro (health + logs + estado no banco + artefatos), com exit 0/1. É o teste de
fio de fronteira de integração (Plataforma de Integração).
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 a fonte, não a imagem renderizada. A figura de capa do livro pode
ser SVG autoral, com o Mermaid-base junto (Convenções de doc).
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
dev/api/ (linkada do mapa do código — nunca órfã).
pipeline.yml¶
O workflow único de CI/CD do app no GitHub Actions (decisão 0027),
à la carte: um job decide liga gate/docs/build_*/deploy por evento
(push, tag, workflow_dispatch), e os alvos de build vêm do app.json build.targets
(jar/native/web). Repo de perfil config usa o pipeline-config.yml.
GraalVM native-image¶
Compilação AOT que transforma o app Micronaut num binário nativo — RSS/imagem
menores, boot quase instantâneo, sem JVM em runtime. O server Micronaut é native por padrão
e só declara jar com motivo (decisão 0033);
a casa usa a Community Edition. Bloqueio conhecido: Apache POI (XMLBeans) não roda em native
→ ler XLSX com FastExcel (decisão 0023).
xadm-commons¶
Repo multi-módulo da casa onde vive a infra transversal idêntica cross-app (auth, RFC-7807/health/
versão, M2M, storage, teste, powersync, ingestão) — cada módulo com SemVer próprio, publicado como
artefato Maven público em fonte.xadm.biz (group br.com.xadm). App Micronaut elegível consome
por versão, não recopia (baseline da casa, Engenharia). Decisão 0019.
Forgejo¶
A forja Git da X-Adm: repositórios, issues, pull requests e o registro de pacotes; o CI roda no GitHub Actions (decisão 0027). Não-devs editam Markdown pela interface web dele. Mais.
Coolify¶
PaaS self-hosted que roda os containers: puxa a imagem que o pipeline.yml buildou quando o
control-plane dispara o deploy. Builda do git só os recursos listados em
Deploy — este site entre eles. 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.