evolutionary-modular-architecture

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. Keep aggregates cohesive (do not over-split a transactional Core).

Exit: context map + table-ownership map (one module = its tables).

Phase 3 — Module internals (flat-by-aggregate)

Read references/flat-by-aggregate.md. Inside each module, organize by aggregate, not by technical layer: 1 business concept = 1 folder; technical layers become file suffixes (.entity.ts, .service.ts, .controller.ts). Keep depth ≤ 2 (flat) or ≤ 3 (subdomain-based). The Clean Architecture dependency rule still holds (presentation → application → domain ← infrastructure) — it is just expressed by suffixes and co-location, not by layer folders. Use the 6-criteria test to decide flat vs subdomain-based; default to flat.

Exit: a folder layout per module and a flat-vs-subdomain decision with rationale.

Phase 4 — Communication & Anti-Corruption Layer

Read references/acl-and-communication.md. Every external system goes behind a Port + Adapter (ACL) — including internal services owned by other teams. The domain defines ports in its own language; adapters translate the external model in and out. Between internal modules: synchronous only inside an aggregate (one ACID transaction); events via the transactional outbox across modules, with idempotent consumers. Add SSE for server-to-client real-time when the UX needs push.

Exit: list of ports + adapters; list of domain events with the module.aggregate.action naming; sync-vs-async decisions.

Phase 5 — Resilience

Read references/resilience.md. Wrap every external/inter-service call: timeout → circuit breaker → retry (capped exponential backoff + full jitter). Only retry idempotent operations (require an idempotency key for writes). Cap retries with a budget (~10% of traffic), trip the breaker on a sliding-window error rate, and give every breaker a named fallback. Add durable execution only when a long-running, multi-step process must survive restarts.

Exit: a resilience policy applied to each adapter, plus idempotency keys for writes.

Phase 6 — Stack & evolution

Read references/stack-2026.md. Choose the concrete stack and call out the trade-offs (runtime, API style, cache, real-time transport). Then state the evolution path: stage 1 (modular monolith + clear boundaries, with events/outbox already in place) is the current state; promote a module to its own app/database only when its own metrics justify it.

Exit: stack table + evolution note.

Phase 7 — Document the architecture (HTML)

Produce a polished, self-contained HTML architecture document with elegant hand-drawn-style SVG diagrams. Read references/architecture-doc.md and start from assets/architecture-template.html: copy the template, keep its CSS and visual system intact, and replace the placeholder content. Build the standard sections (overview, domains, principles, monolith map, bounded contexts, ACL, communication, front-to-back, modules, resilience, real-time, evolution, stack) and number diagrams sequentially ("Diagram N — ..."). Preserve the visual identity: palette, Lato + JetBrains Mono fonts, rounded rectangles, arrow markers, soft gradients, and italic captions. The output is one HTML file that opens directly in a browser — no build step.

Exit: a single self-contained HTML file with consistent diagrams and working in-page navigation.

---

Decision rules (cheat sheet)

• Subdomain class: competitive advantage → Core; business-specific but not differentiating → Supporting; solved problem you consume → Generic.
• Tactical intensity: full (rich aggregates, VOs, invariants, events) in Core; moderate in Supporting; minimal in Generic (forcing richness where there is no invariant is over-engineering). Details in references/ddd.md.
• Flat vs subdomain: flat by default (depth 2). Go subdomain-based (depth 3) only when 4+ of 6 criteria hold: different personas, authorization, execution model, scaling, deployment, failure isolation. Details in references/flat-by-aggregate.md.
• Sync vs event: sync inside one aggregate (atomicity matters); event via outbox across modules (tolerates eventual consistency).
• Durable execution: add it only for long-running, multi-step, must-resume processes — not for ordinary requests.

Hard rules (non-negotiable)

• Each module writes only its own tables; cross-context links are by id, validated in code (enforce-module-boundaries).
• No direct cross-module imports — communicate via facade/contract or event.
• Every external system sits behind a port + ACL — no vendor model leaks into the domain.
• Retry only idempotent operations; writes carry an idempotency key.
• Modular principles (P1–P10) beat structural ones (P11–P19). If co-locating would force a cross-module entity import, use a facade + DTO; if splitting an aggregate would break a transaction, keep it together.

---

Automated checks

Make the principles executable instead of relying on review. Run these in CI and before merge (both are zero-dependency Node ESM scripts; pass the libs/packages root, or let them autodetect):

• node scripts/validate-structure.mjs [root] — enforces flat-by-aggregate (P11–P17): no technical-layer folders, no single-file folders (except __test__/), depth ≤ 3, no README inside aggregates.
• node scripts/validate-boundaries.mjs [root] — enforces modular boundaries (P1, P3, P8): no deep cross-module imports (only via barrel/facade), no duplicate or unprefixed entity names, no cross-context relations.

Both exit non-zero on violation and print the offending paths. Treat structural failures as blocking; treat boundary findings as blocking once the team adopts the convention.

---

Examples

Example 1: Design a new platform

User says: "Desenhe a arquitetura de uma plataforma de contas a pagar que lança no ERP do cliente."

Actions:

1. Phase 1 — discover subdomains; classify (e.g., Payables and Operations as Core; Documents/Audit/Gamification as Supporting; Identity/Notifications as Generic).
2. Phase 2 — context map + one-database, table-per-module ownership.
3. Phase 3 — flat-by-aggregate layout per module.
4. Phase 4 — ERP/ticketing/storage behind ports + ACL; events via outbox; SSE for the operator queue.
5. Phase 5 — resilience policy on the ERP adapter (idempotency key = payment id).
6. Phase 6 — 2026 stack + evolution note (one deploy now).

Result: a context map, module layouts, a port/adapter list, a resilience policy, and a stack + evolution plan — each grounded in the matching reference.

Example 2: Organize a module

User says: "Como organizo o módulo de billing?"

Actions: read references/flat-by-aggregate.md; propose billing/subscription/, billing/invoice/, billing/payment/ with co-located files and __test__/; run the 6-criteria test (billing = flat). Result: a flat folder tree with rationale and the dependency rule preserved via suffixes.

Example 3: Decouple from a vendor

User says: "Não quero ficar preso ao OMIE."

Actions: read references/acl-and-communication.md; define ErpLedgerPort in domain language; implement OmieAdapter; translate the OMIE model at the boundary; show that swapping ERPs means swapping the adapter. Result: a port interface + adapter plan; the domain never imports vendor types.

---

Anti-patterns / red flags

• ❌ Microservices or many databases from day one ("it feels big" is not a reason).
• ❌ Technical-layer folders (core/service/, http/controller/, persistence/entity/) inside a module — that is the legacy pattern flat-by-aggregate replaces.
• ❌ A module reading or writing another module's tables.
• ❌ Vendor SDK types leaking into the domain (no ACL).
• ❌ Retrying non-idempotent writes; retries without backoff + jitter; retries with no budget.
• ❌ Splitting a cohesive transactional Core into event-coupled fragments.
• ❌ Forcing rich tactical DDD on a Generic subdomain that has no invariants.

Reference guide

| Load this file | When |

| --- | --- |

| references/principles.md | You need the exact principle text, or to resolve a structural-vs-modular conflict. |

| references/ddd.md | Phase 1–2: classifying subdomains, drawing the context map, deciding tactical intensity. |

| references/flat-by-aggregate.md | Phase 3: laying out a module; flat vs subdomain; scaffolding; facades; tests. |

| references/acl-and-communication.md | Phase 4: ports/adapters/ACL, events + outbox, SSE. |

| references/resilience.md | Phase 5: backoff/jitter, circuit breaker, idempotency, bulkhead, durable execution. |

| references/stack-2026.md | Phase 0/6: concrete stack choices and trade-offs. |

| references/architecture-doc.md + assets/architecture-template.html | Phase 7: producing the HTML architecture document and its diagrams. |

| scripts/validate-structure.mjs, scripts/validate-boundaries.mjs | Validation: enforcing structure and module boundaries in CI or before merge. |