My House - Scoring API para priorização de famílias em habitação social com Arquitetura Hexagonal (Ports & Adapters)

Código Fonte

"What goes inside the hexagon? I don't care." - Cockburn

Diagrama de fluxo da arquitetura Ports and Adapters

My House é uma Scoring API para priorização de famílias em um programa de habitação social: a API recebe um conjunto de famílias (renda total e dependentes), calcula uma pontuação para cada uma segundo regras de negócio e retorna as famílias elegíveis ordenadas por score. O foco do projeto não é o CRUD em si, mas usar um domínio pequeno e com regras reais para exercitar a Arquitetura Hexagonal (Ports & Adapters) de ponta a ponta, mantendo o núcleo de negócio 100% independente do Spring.

A ideia central da Arquitetura Hexagonal é a regra de dependência: tudo aponta para dentro. O domínio não sabe que existe Spring, HTTP ou banco: quem conhece o domínio são as bordas. A comunicação com o mundo externo acontece por portas (interfaces definidas pelo domínio) que os adapters da infraestrutura implementam. Um POST /families entra por um adapter HTTP, atravessa um caso de uso e chega ao núcleo; a persistência é acessada de volta por uma porta, nunca por uma dependência direta. Na prática: trocar in-memory por Postgres, ou REST por mensageria, é mexer só na borda, e o núcleo fica intacto.

Design & Decisões de Arquitetura

Domínio isolado de framework: as entidades (Family, Dependent) e as regras de scoring são Java puro, sem anotações do Spring, sem dependência de infraestrutura. O framework fica na borda.
Ports & Adapters: as portas são interfaces de gateway (RegisterFamiliesGateway, ListFamiliesGateway) definidas no domínio; a persistência entra por adapters (hoje in-memory), substituíveis por um banco real sem tocar no núcleo.
Strategy para as regras de elegibilidade: a pontuação é abstraída pela interface Scoring, com a implementação MyPopularHouseScoring. Trocar o critério do programa é plugar outra estratégia, sem alterar casos de uso nem entidades.
Casos de uso explícitos: cada operação é um use case com Input/Output próprios sob um contrato comum (UseCaseContract<I, O>): RegisterFamilies e ListEligibleFamilies.
IoC manual: a composição das dependências é feita em providers próprios, deixando claro quem monta o quê e reforçando que o domínio não conhece o container.
Builder para consulta: paginação e ordenação passam por um Filter montado via Builder (sortBy, pageNumber, pageSize).
Fábricas na entidade: Family.create() (nova, calcula o score na construção) e Family.restore() (reidratação), evitando estados inválidos.

As regras em si (faixas de renda, bônus por dependentes) são só o miolo do hexágono, propositalmente simples e trocáveis via Strategy. O que importa aqui é que elas vivem no domínio, sem nenhum acoplamento com Spring, HTTP ou persistência.

API REST

POST /families: registra um lote de famílias com renda e dependentes.
GET /families/eligibles: lista as famílias elegíveis ordenadas por pontuação (com paginação).

Qualidade & Testes

Testes unitários no núcleo (entidade Family e a estratégia de scoring), sem subir o Spring.
Domínio testável em isolamento, consequência direta de separar regras de negócio da infraestrutura.

Stack

Java 17
Spring Boot (apenas na borda: controllers HTTP e bootstrap)
Maven
Docker