Plataforma

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-23

Aplica-se a: todo perfil.

A X-Adm entrega software como um conjunto de aplicações pequenas. Elas rodam na nuvem, conversam entre si por contratos explícitos e compartilham a mesma infraestrutura. Esta área responde três perguntas, nesta ordem.

1. Quais aplicações existem e onde cada uma roda — Os apps na nuvem.
2. Como elas conversam — Plataforma de Integração.
3. Sobre o que elas rodam — Infraestrutura.

Por onde começar

Se você quer…	Leia	O que encontra
o mapa das aplicações	Os apps na nuvem	inventário por app: cliente, papel, endereço e stack
entender o desenho dos dados	Plataforma de Integração	topologia, os quatro tipos de fluxo, taxonomia de papéis
integrar um cliente, passo a passo	Manual de integração	os três cenários (tempo real, relatórios, entrada no X-Adm), cliente novo, tokens e verificação
saber quem chama quem	Arestas concretas	chamador, chamado, endpoint e autenticação, linha a linha
garantia de que o dado chega	Entrega garantida	os três mecanismos e a fronteira de cada um
o caminho do código até o ar	Infraestrutura	CI, registro de imagens, control-plane, Coolify, Traefik
ligar erro, arquivo ou métrica num app	Central de Apps	o app.json, o broker de provisão, o que é build-time
operar um recurso no ar	Operação no Coolify	env, domínio, banco e as armadilhas já validadas

O que se replica e o que é único

Fechar um contrato novo não cria uma cópia inteira da plataforma. Parte das peças nasce de novo para cada cliente; parte já existe e passa a atender mais um. Saber de que lado cada app está é o que explica o custo de entrar um cliente — e por que dois clientes nunca enxergam o dado um do outro.

flowchart TB
    subgraph noCliente["No servidor do cliente — fora da nuvem"]
        erp["ERP X-Adm"]
        ic["integrador-client"]
    end
    subgraph porCliente["Na nuvem — uma cópia por cliente"]
        pi["integrador-server<br/>int.&lt;cliente&gt;"]
        esp["apps específicos<br/>excel · pied · webstorm"]
        pg[("banco do cliente<br/>o barramento")]
        ps["PowerSync<br/>ps.&lt;cliente&gt;"]
        cons["apps consumidor<br/>bi.&lt;cliente&gt;"]
    end
    subgraph unica["Na nuvem — instância única para todos"]
        sascar["integrador-sascar"]
        central["central-backend<br/>central-ui"]
    end
    erp --> ic
    ic -- "push tempo real" --> pi
    ic -- "batch XLSX" --> esp
    pi -- "escreve o espelho" --> pg
    esp -- "escreve as tabelas dele" --> pg
    pg --> ps
    ps -- "leitura e write-back" --> cons
    ps -- "leitura e write-back" --> ic
    pi <-- "REST, token por destino" --> sascar
    central -. "configura, não troca dado" .-> pi

O banco do cliente é a fronteira. Ele é o ponto de encontro das peças e, ao mesmo tempo, o limite do que cada cliente alcança. Não existe banco comum de negócio entre clientes — por isso a multiplicidade da figura importa tanto quanto as setas.

Uma cópia por cliente. O espelho do ERP, os apps feitos sob medida, o banco e a instância de sincronização. É o que o inventário lista cliente a cliente.

Instância única. O integrador-sascar é único porque o parceiro do outro lado é o mesmo para todos — replicá-lo por cliente não traria nada. A Central de Apps é única por outra razão: ela não participa de fluxo de dado nenhum, só configura os demais.

Fora da nuvem. O ERP e o integrador-client rodam no servidor do cliente. É a única fronteira da figura em que a X-Adm não controla o hardware, e é por isso que o transporte ali é offline-first.

O que esta área não cobre

As regras de como escrever código, testar e versionar estão em Engenharia. A norma que governa as duas áreas está na constituição. A documentação de cada aplicação é publicada pelo próprio repo e aparece em Aplicações.