evolutionary-modular-architecture

Start with strategic DDD to classify subdomains as Core, Supporting, or Generic, then draw a context map with clear state ownership per module. Organize each module flat-by-aggregate, put external systems behind ports and adapters, and keep everything in one deploy until metrics justify splitting.

Default to a modular monolith with one deploy unless a hard constraint requires otherwise. Promote a module to its own app or database only when its own scaling, failure-isolation, or deployment metrics justify it, since strong logical boundaries make that evolution possible without a rewrite.

Define a port in your domain's own language, such as an ErpLedgerPort, and implement it with an adapter that translates the vendor model at the boundary. Swapping vendors then means writing a new adapter while the domain never imports vendor types.

Flat-by-aggregate means one business concept equals one folder, with technical layers expressed as file suffixes like .entity.ts, .service.ts, and .controller.ts instead of layer folders. Depth stays at two or three levels, and the Clean Architecture dependency rule is preserved through suffixes.

Skip it for simple CRUD applications with a handful of endpoints where framework defaults are enough. For NestJS-specific deep implementation use a dedicated NestJS modular skill, and for reviewing a single anemic domain model use a tactical DDD skill instead.

Compose layers in order: timeout, circuit breaker, then retry with capped exponential backoff and full jitter. Only retry idempotent operations, require idempotency keys for writes, cap retries at roughly ten percent of traffic, and give every breaker a named fallback.