software-architect

Start with layered architecture for CRUD apps, small teams, and prototypes since it has low complexity. Upgrade to clean architecture when business logic becomes complex and the application is long-lived, following the YAGNI principle of adding patterns only when they reduce complexity.

Use DDD only when the domain is genuinely complex with multiple bounded contexts. Apply aggregates to enforce invariants at a root entity, keep repositories only at the aggregate root level, and use domain events to communicate across bounded contexts.

Hexagonal architecture (ports and adapters) fits systems with multiple I/O adapters like REST, CLI, and queues, where ports are interfaces defined by the application. Clean architecture emphasizes concentric dependency rules where inner layers never import outer layers.

Package by feature is preferred: each module like user/ or order/ owns its entity, repository interface, service, and controller. Cross-module access goes through well-defined APIs rather than direct database queries, keeping cohesion high and coupling low.

Use CQRS only when read and write models diverge significantly, such as heavy reporting needs. Use event sourcing only when a full audit trail or temporal queries are an actual requirement, since both patterns carry high complexity costs.

Define architectural fitness functions and run them in CI: zero circular dependencies via dependency-cruiser, forbidden import rules via import-linter so domain never imports infrastructure, plus coverage, build time, and bundle size thresholds.