# Evolutionary Modular Architecture

Guides design and implementation of evolutionary modular-monolith platforms with DDD...

- Repository: https://github.com/tech-leads-club/agent-skills (7121 stars)
- Category: Design
- License: CC-BY-4.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add tech-leads-club/agent-skills --skill evolutionary-modular-architecture -g -a claude-code -y`
Codex: `npx skills add tech-leads-club/agent-skills --skill evolutionary-modular-architecture -g -a codex -y`
Cursor: `npx skills add tech-leads-club/agent-skills --skill evolutionary-modular-architecture -g -a cursor -y`
Gemini CLI: `npx skills add tech-leads-club/agent-skills --skill evolutionary-modular-architecture -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add tech-leads-club/agent-skills`

## Description

Guides design and implementation of evolutionary modular-monolith platforms with DDD (strategic + tactical), flat-by-aggregate organization, an Anti-Corruption Layer for vendor independence, a transactional outbox for events, smart resilience (backoff with jitter, circuit breakers, idempotency), and a polished architecture HTML document with elegant SVG diagrams. Use when designing a platform or backend, defining bounded contexts, organizing modules and folders, choosing monolith vs microservices, decoupling from an external service (ERP, storage, AI), making calls resilient, adding real-time push, picking a 2026 TypeScript stack (Nx, NestJS, React), or producing an architecture document or diagram. Also triggers on 'modular monolith', 'bounded contexts', 'flat-by-aggregate', 'ports and adapters', 'architecture diagram'. Do NOT use for simple CRUD, NestJS-only deep implementation (use nestjs-modular-monolith), or pure domain-model review (use tactical-ddd).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Evolutionary Modular Architecture

Design and build platforms as an **evolutionary modular monolith**: strong logical boundaries from day one (DDD bounded contexts, flat-by-aggregate modules, an Anti-Corruption Layer around every external system, event-driven communication, resilience by default) while keeping physical boundaries (separate deploys, separate databases) as a later, optional step. Start simple, evolve granularity only when the product and the team justify it, never reverse-engineer microservices from hype.

## When to use this skill

- Designing a new platform, backend, or service from scratch.
- Defining bounded contexts and a context map for a domain.
- Deciding how to organize a module's folders and files.
- Choosing between monolith, modular monolith, and microservices.
- Integrating with (or decoupling from) an external vendor: ERP, ticketing, storage, payment, AI, identity, durable-workflow engine.
- Making external/inter-module calls resilient.
- Adding real-time server-to-client updates.
- Picking a modern (2026) full-stack TypeScript stack.

## When NOT to use it

- Simple CRUD with a handful of endpoints, framework defaults are enough.
- Deep, NestJS-specific implementation detail, prefer `nestjs-modular-monolith`.
- Reviewing or refactoring a single domain model for anemia, prefer `tactical-ddd`.

---

## The one rule that governs everything

**Separate the logical boundary (always strong) from the physical boundary (evolutionary).** Modules, contracts, state ownership, and the Anti-Corruption Layer are non-negotiable from day one. Whether a module is its own deploy or its own database is an **operational** decision made later, never a structural prerequisite. This is what lets the system start as one deploy and grow without a rewrite.

The rest: https://github.com/tech-leads-club/agent-skills/blob/HEAD/packages/skills-catalog/skills/(architecture)/evolutionary-modular-architecture/SKILL.md