java-architecture-review

Start by mapping the package structure with find commands, then check whether the organization follows package-by-layer, package-by-feature, or hexagonal style. Next verify dependency direction: the domain layer must have zero framework imports, and adapters may depend on the domain but never the reverse.

Package-by-layer groups classes by technical role (controller, service, repository), which scatters related code and scales poorly. Package-by-feature groups all classes for one business capability together, making boundaries clearer and features easier to extract into modules.

Search the domain package for framework imports using grep for patterns like 'import org.springframework' or 'import javax.persistence'. Any match means the domain is coupled to infrastructure; fix it by defining pure port interfaces in the domain and implementing them in adapter packages.

The main ones are the big ball of mud (one package with 100+ classes), util dumping grounds, anemic domain models where entities hold only getters and setters, circular package dependencies, and framework annotations polluting domain objects.

Hexagonal architecture fits complex domains where testability and framework independence matter most, since it isolates pure business logic behind ports and adapters. For simpler applications, package-by-feature delivers clear boundaries with less structural ceremony.