/evolutionary-modular-architecture

name: evolutionary-modular-architecture
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).
license: CC-BY-4.0
metadata:
  author: Felipe Rodrigues - github.com/felipfr
  version: 1.0.0

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.

A useful mental image: the house has well-divided rooms (modules). Inside each room things sit out in the open, grouped by what they are for (flat-by-aggregate) — not buried in nested drawers (technical-layer folders). The floor plan (boundaries) is what matters most.

---

Core model (load the matching reference when you go deep)

| Topic | What it covers | Reference | | --- | --- | --- | | Principles | 10 modular (P1–P10) + 9 structural (P11–P19) + conflict hierarchy | `references/principles.md` | | DDD | Strategic (subdomains, context map, integration patterns) + tactical (rich aggregates, intensity by subdomain) | `references/ddd.md` | | Module internals | Flat-by-aggregate, suffixes, depth, flat vs subdomain test, scaffolding | `references/flat-by-aggregate.md` | | Communication | Ports & Adapters / ACL, events + transactional outbox, SSE real-time | `references/acl-and-communication.md` | | Resilience | Backoff + full jitter, circuit breaker, retry budget, idempotency, bulkhead, timeouts | `references/resilience.md` | | Stack 2026 | Frontend, backend, data, observability, durable workflow, decisions | `references/stack-2026.md` | | Architecture doc | Building the elegant, self-contained HTML architecture document with SVG diagrams | `references/architecture-doc.md` + `assets/architecture-template.html` | | Validation | Deterministic checks for structure and module boundaries | `scripts/validate-structure.mjs`, `scripts/validate-boundaries.mjs` |

Do not load all references at once. Read a reference only when the current phase needs it (the workflow below states when).

---

Workflow

Use this whether you are **designing** a new system or **reviewing** an existing one. Move through phases in order; each has an exit criterion. State assumptions explicitly; if the domain is unclear, ask before guessing.

Phase 0 — Frame the scope

Confirm: is this a new platform, a new module in an existing one, or a review? Confirm the runtime/stack constraints (default target is the 2026 TypeScript stack — see `references/stack-2026.md`). Default to **one deploy** (modular monolith) unless a hard constraint says otherwise.

Exit: scope and constraints written down.

Phase 1 — Domain discovery (DDD strategic)

Read `references/ddd.md`. Identify subdomains from the business language, classify each as **Core**, **Supporting**, or **Generic**, and find the ubiquitous language of each. Do not group by technical layer. If multiple bounded-context interpretations exist, present them — do not pick silently.

Exit: a list of candidate bounded contexts, each classified, with one-line responsibility and key aggregates.

Phase 2 — Boundaries & context map

Draw the context map: which contexts exist, how they relate (Customer/Supplier, Conformist, Open Host Service, Published Language, Shared Kernel, Anti-Corruption Layer), and which are Core. Decide **state ownership**: one database is fine, but each module is the **sole writer of its own tables** — no foreign keys across module boundaries; reference other contexts by id. K