Pular para conteúdo

Stack da casa

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

Aplica-se a: todo perfil e toda stack.

A Engenharia X-Adm é opinativa: prescreve qual stack e quais ferramentas por tipo de app. É decisão de plataforma, não preferência por app. Os defaults são fortes; o desvio é exceção documentada numa decisão em decisoes/.

Matriz app → stack

Tipo de app Stack Notas
Servidor / API Micronaut (Java) native por padrão
Servidor + view simples Micronaut + JTE server-rendered, kit de UI da casa
Cliente / web / desktop Flutter web e/ou desktop
Mobile Flutter sem exceção esperada
App simples / CLI / worker Java puro (sem framework) + picocli no CLI
ERP ZIM parser local futuro (nunca expor fonte à IA)

Defaults transversais

  • Arquitetura: package-by-feature, inclusive nos servidores. Transversal em comum/core; pipeline genérico no kernel + uma estratégia (interface) para o que varia.
  • HTTP: OkHttp nos arquétipos Java sem framework (CLI/worker). Dentro de um app Micronaut, a chamada app ↔ app é @Client declarativo + @Retryable (Java/Micronaut).
  • JSON: Micronaut serde (@Serdeable = allowlist de segurança, todo DTO HTTP).
  • Java: 25 (LTS). A versão vem do docs/app.json toolchain.java, que o pipeline.yml exporta para o gate e os builds (0027).
  • Build: Gradle (Kotlin DSL) + invólucro versionado + pin de dependências; gate único ./gradlew check.
  • Testes: JUnit 5 + WireMock sobre fixtures anonimizadas.
  • Dinheiro / fiscal: BigDecimal, nunca double/float.
  • Logging e exit codes: por arquétipo, com dono em Java.
  • Banco: PostgreSQL + Flyway, migrations congeladas por checksum; modelo design-first em projeto/modelagem.md.
  • Flutter (cliente): arquitetura PFA + flutter_it — get_it (DI) + watch_it (reativo) + command_it (ações); roteador go_router (path URL strategy). Baseline: get_it ^9 · watch_it ^2.4 · command_it ^9.5 · go_router ^17 (Flutter 3.44 / Dart 3.12). Detalhe em Flutter.

Comentário no código

  • Comentário de linha ou de bloco: uma linha, direta, só para o porquê que o código não mostra — restrição (inclusive a versão mínima de uma API externa que o código exige), invariante, efeito colateral. O óbvio não se comenta. A linha cabe no limite de coluna da stack (120 no Java, pelo checkstyle; 80 no Dart, dartdoc incluso; HTML e JS, sem formatter na casa, não têm limite) e vai acima do código. No Dart o comentário entra na conta do dart format onde estiver: no fim da linha, quebra o código em volta; em linha própria dentro de uma expressão (closure, coleção, argumento), o recuo dele depende do layout, e o formatter escolhe o layout em que ele cabe — mudar o tamanho do comentário re-flui a expressão, e layout torto em volta dele (quebra entre o tipo e o nome) se cura encurtando-o.
  • Javadoc e dartdoc de API seguem o padrão da linguagem e documentam o contrato: frase-resumo, parágrafos, @param, @return, @throws e o contrato de exceção. É o que o site da API publica; a regra da uma linha não vale para eles. O contrato se escreve no presente: @since e @deprecated com o substituto são contrato e ficam; data, caso, número de spec ou de plano não entram — o porquê pode linkar a decisão.
  • A história não mora no código: o bug que motivou, a feature, a data, o incidente e o "antes era X" vão para a mensagem de commit, o CHANGELOG ou a decisão.
  • Armadilha de linguagem, framework ou plataforma não vira comentário: vira linha na seção Armadilhas da página da stack (sintoma → causa → cura). Achada num app, volta ao central como feedback; a seção nasce na primeira armadilha registrada.
  • Template do kit pode abrir com as instruções de adaptação, uma linha cada — é instrução para quem copia.

Configs de referência

O central provê arquivos de referência por stack, para ninguém copiar config de outro app: