Pular para conteúdo

0007 — Plataforma de Integração vira norma central (§8)

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-07 · Decidido em: 2026-07-07

Contexto

A arquitetura-alvo de integração da casa (o hub como cópia fiel do X-Adm + connector PowerSync, verticais com porta própria, reatores que consomem o banco, tudo organizado por shape do fluxo) amadureceu num draft (rev. 3) na raiz deste repo. É norma da casa — vale para toda integração e todo cliente — mas não tinha presença na constituição: vivia só no draft. O §7 (Central de Apps) já provou o molde de uma plataforma que mora na constituição: norma curta na constituição + página de detalhe operável + repo de implementação. A plataforma de integração é a irmã disso.

Decisão

Dar à Plataforma de Integração a mesma presença central do §7, separando núcleo estável de design volátil:

  • Norma curta na constituição — nova §8: os invariantes duráveis — organiza-se por shape; a taxonomia (hub/vertical/reator/app consumidor, ortogonal ao grupo do §5); owner-writes no barramento; transporte padronizado por direção; PowerSync bidirecional; bi-commons como plumbing compartilhado. A §8 nomeia os papéis e delimita do §7 (o §7 = como um app liga na infra; o §8 = como integrações são arquitetadas).
  • Detalhe operável — Plataforma de Integração: a taxonomia detalhada, os 4 shapes, as fronteiras/owner-writes e o contrato de transporte. É a destilação do núcleo estável; o contrato preciso move-se aqui (barato), não na constituição.
  • Tech — PowerSync: o padrão praticado (connector, write-back, JWKS inline, edition:3, callback-200), e o invariante owner-writes no §Banco do Java/Micronaut.
  • Design volátil fica fora do central: o inventário, o roadmap de migração e as decisões D0–D13 vivem na arquitetura-alvo, no repo do integrador — evolui sem re-bumpar a constituição. Esta decisão não os recapitula; aponta para lá.

Alternativas consideradas

  • Deixar o draft na raiz do central (ou como página avulsa): não vira norma citável, e o volátil (roadmap/D0–D13) obrigaria re-bump da constituição a cada evolução. Preterido.
  • Importar todo o desenho concreto para o central: normatizaria um draft ainda em fluxo (§1.2) e acoplaria a constituição ao ritmo do roadmap. Preterido — só o núcleo estável sobe; o resto fica no repo da integração e é linkado (§1.9, um dono por fato).

Consequências

  • A arquitetura.md migrou para integracao/integrador/docs/projeto/arquitetura.md e publica em docs.xadm.biz/aplicacoes/integrador/projeto/arquitetura/; a §8 e a integracao.md linkam essa URL para o concreto. O draft saiu da raiz do central.
  • Glossário ganhou 7 verbetes (shape, hub, vertical, reator, barramento, owner-writes, bi-commons), cada um linkando a integracao.md como dono da definição.
  • Um decision record espelho nasce no integrador/docs/decisoes/ no início da implementação (como o próprio draft previa) — esta 0007 é a meta-decisão de adoção, não o registro de implementação.
  • Bump minor da constituição (0.17.36 → 0.18.0): seção normativa nova.