Engenharia¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-19
Esta área é o lado como construir do padrão da plataforma (o lado como documentar é a Documentação). É opinativa: além de conceitos, prescreve qual stack e quais ferramentas por tipo de app — para que um app novo só siga a constituição (Documentação + Engenharia) e seja feliz.
Por onde começar¶
- Stack da casa — a matriz app → stack → ferramentas e os defaults transversais. É a porta: comece aqui.
- Por stack: Java / Micronaut · Java (CLI / worker) · Flutter.
- Versionamento e release — SemVer,
/xadm-release,/health, health check. - PowerSync — o transporte — o padrão praticado de sync/connector/write-back (transversal Java+Flutter); a arquitetura de integração está na constituição §8.
- Segurança — o piso — authn/authz fail-closed, validação de input, segredos e o checklist do revisor.
- CI, gates e testes — gate de CI por stack, branch
master, níveis de teste e o detalhe da definição de pronto.
Princípios¶
Defaults fortes e opinativos. O desvio é exceção documentada (uma decisão em
decisoes/ que o justifica), não escolha livre por app — nem mandato cego: um caso
legítimo desvia, mas declarando o porquê.
Simplicidade primeiro (sem over-engineering). Busque o caminho mais simples que satisfaz a necessidade real e presente — não a solução mais genérica, abstrata ou "extensível". Abstração, camada, generalização e configurabilidade só entram com necessidade concreta agora, não "vai que um dia". YAGNI: código que não existe não tem bug. Se a solução está ficando complexa, pare e procure a versão enxuta antes de seguir. (É o irmão de engenharia do "enxuto por padrão" da constituição §1.5, que vale para a doc.)
Reusar a infra da casa antes de inventar mecanismo. Ao desenhar transporte ou gatilho entre serviços (sync, notificação, deploy, fila), confirme a infra que já existe antes de propor um mecanismo novo — e nunca assuma um que não existe. A casa já tem PowerSync acoplado à fonte da verdade (o Postgres por cliente é o barramento — ver Plataforma de Integração e a constituição §8); inventar um webhook/comando paralelo sem checar gera decisão auto-contraditória, que depois se reescreve. Verificar a infra existente > presumir um mecanismo. (É o "reusar > reinventar", primo do YAGNI acima.)
Arquétipos de app¶
| Arquétipo | Stack | Ênfase de engenharia |
|---|---|---|
| Integração / processador | Java/Micronaut | contrato, schema, guarda de fronteiras, integração |
| Dashboard / app de usuário | Flutter Web | analyze/test, widgets, fronteiras de import, screenshots |
| Ferramenta / job | Java puro / CLI | lint + testes da lógica pura; exit codes |
| Site estático / docs | MkDocs | build --strict, lint Mermaid, manifesto |
As páginas por stack (guarda de fronteiras, CI/testes, skills) entram conforme os pilotos Micronaut e Flutter fecham — a Engenharia detalha o "como" de cada ferramenta a partir de padrão provado, não aspiracional.