Blog / arquitetura
Por que a Kelly Academy usa arquitetura hexagonal (e quando eu não usaria)
Arquitetura importa num SaaS na hora em que algo fora dele muda. Na Kelly, isso já aconteceu mais de uma vez.
Eduardo Ciudad
9 de novembro de 2026 · 2 min de leitura
package eduar.studymindredacao.domain.port; import eduar.studymindredacao.domain.model.ResultadoAvaliacaoIA;import eduar.studymindredacao.domain.model.SolicitacaoAvaliacao; public interface AvaliacaoIAPort { ResultadoAvaliacaoIA avaliar(SolicitacaoAvaliacao solicitacao);}EM 30 SEGUNDOS
- 1A Kelly depende de três coisas que eu não controlo: IA, pagamento e e-mail.
- 2O domínio diz do que precisa; adaptadores entregam e podem ser trocados.
- 3Custa mais arquivos. Vale quando o que está fora do sistema muda, e num SaaS sempre muda.
01
O problema
Três coisas que eu não controlo
A Kelly Academy corrige redações do ENEM com IA, cobra assinatura e manda e-mail. Qualquer um desses serviços pode mudar de preço, de versão ou de regra, e nenhum deles pergunta antes.
IA
Gemini
Modelo, preço e limites mudam sem aviso.
Pagamento
Stripe
Precisou existir antes de estar pronto.
SMTP
Provedor pode mudar; o fluxo de senha não.
02
A ideia
As regras no centro, o resto do lado de fora
A arquitetura hexagonal é uma forma de garantir que, quando algo de fora mudar, o que muda junto seja pequeno. O centro diz do que precisa. Quem entrega fica do lado de fora.
03
Na prática
Uma redação atravessando o hexágono
Quando o aluno envia um texto, ele passa por quatro lugares. Só o último sabe que o Gemini existe.
RedacaoController
adapter.in.web
Recebe o texto do aluno.
EnviarRedacaoService
application.usecase
Valida o tema e os limites do plano.
AvaliacaoIAPort
domain.port
Pede a avaliação, sem saber quem avalia.
GeminiAvaliacaoAdapter
adapter.out.ia
Monta o prompt e chama o Gemini.
No caso de uso, a chamada é uma linha. Ele fala com a porta, não com o Gemini:
public RedacaoDetalhada enviar(UUID usuarioId, UUID temaId, TipoRedacao tipo,
String texto, OrigemRedacao origem) {
// ...
var resultado = avaliacaoIA.avaliar(
new SolicitacaoAvaliacao(tema.titulo(), texto));
// ...
}O domínio não sabe que o Gemini existe. É por isso que trocar o Gemini é barato.
04
O retorno
Três vezes em que isso pagou a conta
Trocar o modelo de IA
A correção conversa com uma porta, não com o Gemini. Trocar de modelo mexe no adaptador e no prompt; a regra da nota fica onde está.
GeminiAvaliacaoAdapter
Pagamento desligado sem if
Antes do Stripe estar pronto, um adaptador que só responde “ainda não disponível” ocupou o lugar. O e-mail ganhou um igual.
PagamentoDesligadoAdapter
Quase 1.300 testes
Regras de correção, planos e limites de uso são testadas com portas falsas: sem chamar a IA e sem cobrar ninguém.
1.288 @Test no repositório
O segundo é o meu favorito. O pagamento ainda não estava pronto, e o sistema precisava funcionar mesmo assim. Quando o Stripe ficou pronto, troquei o adaptador na configuração. É a mesma lógica do post sobre planos Grátis e Pro sem if.
public class PagamentoDesligadoAdapter implements PagamentoGatewayPort {
static final String MENSAGEM = "Pagamento ainda não está disponível";
@Override
public SessaoCheckout criarSessaoCheckout(SolicitacaoCheckout solicitacao) {
throw desligado();
}
}Trocar o modelo de IA: o que entra no diff
05
O custo
O custo honesto
Mais arquivos, mais interfaces e um mapper entre o banco e o domínio. Para uma tela de cadastro simples, isso é burocracia.
para salvar e ler uma redação no banco. Num CRUD simples, seriam dois.
- 1
Redacao.java
domain.model
- 2
RedacaoRepositoryPort.java
domain.port
- 3
RedacaoRepositoryAdapter.java
adapter.out.persistence
- 4
RedacaoJpaRepository.java
persistence.repository
- 5
RedacaoEntity.java
persistence.entity
- 6
RedacaoPersistenceMapper.java
persistence.mapper
No começo parece lento. O retorno aparece quando algo de fora muda e a mudança cabe num arquivo.
06
A decisão
Quando vale a pena num SaaS
VALE A PENA QUANDO
- ✓O produto depende de serviços que mudam: IA, pagamento, e-mail
- ✓As regras do negócio são o produto
- ✓Vai durar anos e ter mais gente mexendo
- ✓Você quer testar regra sem subir infraestrutura
EU NÃO USARIA QUANDO
- —Landing page ou site institucional
- —CRUD simples, sem regra de verdade
- —MVP para descobrir se alguém quer
- —Script ou automação interna
FIM
O que levar daqui
Arquitetura não é sobre pastas bonitas. É sobre o tamanho do estrago quando algo que você não controla muda. Num SaaS, sempre muda.
O Radar, que foi ao ar este mês, segue o mesmo desenho, porque também depende de um serviço de fora: o Google Analytics.
Eduardo Ciudad
Desenvolvedor backend e fundador da CiudadLab. Escreve sobre o que constrói e coloca no ar.