Pular para conteúdo

Stack da casa

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-19

A Engenharia X-Adm é opinativa: prescreve qual stack e quais ferramentas por tipo de app. É decisão de plataforma (a casa escolheu), não preferência por app.

Regra: defaults fortes; o desvio é exceção documentada (uma decisão em decisoes/ que o justifica), não escolha livre — nem mandato cego.

Matriz app → stack

Tipo de app Stack Notas
Servidor / API Micronaut (Java) —
Servidor + view simples Micronaut + Thymeleaf server-rendered
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 — default único, inclusive servidores (o piloto Micronaut migrou para package-by-feature e provou). Transversal em comum/core; pipeline genérico no kernel + uma estratégia (interface) para o que varia.
  • HTTP: OkHttp nos arquétipos plain-Java (CLI/worker). Dentro de um app Micronaut, a chamada app↔app usa o @Client declarativo + @Retryable (gerado do OpenAPI do receptor — decisão 0020), não OkHttp: o cliente já vem no runtime e integra DI/filtros/observabilidade (Java/Micronaut §Específico).
  • JSON: Jackson / Micronaut serde (@Serdeable = allowlist de segurança, todo DTO HTTP).
  • Java: 25 (LTS) — versão da casa; a imagem de CI ci-java:25 e o setup/SDKMAN local seguem ela (decisão 0003).
  • Build: Gradle (Kotlin DSL) + wrapper versionado + pin de dependências; gate único ./gradlew check (Java via SDKMAN).
  • Testes: JUnit 5 + WireMock (integração com mock HTTP sobre fixtures anonimizadas).
  • Dinheiro / fiscal: BigDecimal (nunca double/float).
  • Logging: Logback por arquétipo — STDOUT = dados/contrato, STDERR + arquivo = logs (crítico em CLI cujo stdout é consumido).
  • Banco: PostgreSQL + Flyway — migrations congeladas por checksum; modelo design-first em projeto/modelagem.md, evoluído no mesmo PR.
  • CLI: picocli + exceção → exit code (0 ok / 1 parcial / 2 config-auth / 3 externo); sem-flags ⇒ valida config + help; log de observabilidade por requisição (segredo nunca logado).
  • Flutter (cliente): arquitetura PFA + flutter_it — get_it (DI) + watch_it (reativo) + command_it (ações); roteador go_router (path URL strategy, sem #). Baseline provado: get_it ^9 · watch_it ^2.4 · command_it ^9.5 · go_router ^17 (Flutter 3.44 / Dart 3.12). Detalhe e guarda de imports: Flutter.

Configs de referência

Para não copiar config app-a-app (e propagar bugs), o central provê arquivos de referência por stack:

  • Flutter: gitignore-flutter → copie para .gitignore. pubspec.lock é versionado num app (build reproduzível, nunca *.lock); FVM moderno usa .fvmrc versionado (sem o legado !.fvm/fvm_config.json).
  • Java: checkstyle.xml
  • suppressions.xml → config/checkstyle/ (gate ./gradlew check). Detalhe do arquétipo: Java.

O detalhe fino por stack (o "como" de cada ferramenta) entra nas páginas por stack e nas skills, conforme os pilotos fecham. Esta matriz é o esqueleto opinativo que já vale para começar um app novo.