SkillAgentSearch skills...

evolutionary-modular-architecture

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โ€ฆ

Install / Use

npx skills add tech-leads-club/agent-skills --skill evolutionary-modular-architecture

Installs into whichever agent you are using.

About this skill
๐Ÿ“„

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

Our assessment of evolutionary-modular-architecture

evolutionary-modular-architecture scores 89/100 on our quality scale, 468th of 1,153 Content & Media skills we index (top 41%).

Its SKILL.md is 15 KB long, well organised into 23 sections and no code examples: a thorough specification that gives an agent plenty to work with.

With 7,166 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
13/20
Description
15/15
Adoption
16/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 5 days ago, so evolutionary-modular-architecture is actively maintained.
  • Our last check on 2026-10-31 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit โ€” read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-28. Automated pattern scan on 2026-09-28. It catches known dangerous patterns, not every risk โ€” read a skill before letting an agent act on it.

evolutionary-modular-architecture compared with similar skills

All 4 of these similar skills score higher than evolutionary-modular-architecture; compare them before choosing.

SkillScoreStarsUpdatedFormat
evolutionary-modular-architecture (this skill)by tech-leads-club897.2k5d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md
siyuanby siyuan-note10047.3ktodayMCP Server
x402by browser-use100121.0k3d agoSKILL.md

Frequently asked questions

How do I install evolutionary-modular-architecture?
Run npx skills add tech-leads-club/agent-skills --skill evolutionary-modular-architecture. The install tabs above show the steps for each supported agent.
Which AI agents does evolutionary-modular-architecture work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is evolutionary-modular-architecture safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is evolutionary-modular-architecture still maintained?
The repository was last updated 5 days ago, so evolutionary-modular-architecture is actively maintained.

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. 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

Truncated for display โ€” read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars7.2k
CategoryContent
Updated5d ago
Forks571

Languages

TypeScript

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit โ€” see the Safety scan above for what the skill file itself contains.

1 medium
evolutionary-modular-architecture โ€” Universal Skill: Install & Safety Check | SkillAgent