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; docs/design/ em repos anteriores à constituição
v0.4.0). 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/ (docs/rd/
em repos anteriores à constituição v0.4.0; o nome antigo era "RD").
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/ (docs/guias/ em
repos anteriores à constituição v0.4.0; docs/manual/ antes do split
público/privado).
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 (constituição §1.9 — "feature
pronta = andaime apagável sem perda").
Manifesto (de templates)¶
manifesto.json no repo central: a lista mecânica dos artefatos canônicos
(templates, skills, workflows) com sha256 e a versão da constituição em que
cada um mudou (mudou_em). É o que a /xadm-docs usa para detectar cópia
defasada num app.
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¶
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.
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 §8).
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.
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
dev/api/ (linkada do mapa do código — nunca órfã).
Fábrica de imagens de CI¶
Pipeline do central que builda as imagens ci-base/ci-java:<v>/ci-flutter:<v>
usadas pelos container: dos CIs. As versões homologadas vivem na
matriz-baseline.json (fonte única, publicada em /toolchain/) — versão fora
da baseline trava o release (decisão 0003).
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.