---

name: modular-ddd-architecture description: Expert guide for designing and analyzing software architecture using Domain-Driven Design (DDD) and modular architecture principles. Use when someone asks to design a new module, identify domains, analyze code cohesion, plan folder structure, define bounded contexts, create feature folders, or review architecture. Also use when someone says "analyze this codebase", "what domains do we have", "how should I structure this module", "identify bounded contexts", "create a new module", or asks about modular monolith design. Do NOT use for infrastructure/DevOps, database schema design, or API endpoint design. license: CC-BY-4.0 metadata: author: Luiz Nascimento version: 1.0.0

Modular DDD Architecture

Guide an agent to design new modules or analyze existing codebases using Domain-Driven Design (DDD) strategic principles, modular architecture, and feature folder organization. Language-agnostic.

Modes of Operation

This skill operates in two modes based on user intent:

Design Mode

Trigger: User wants to create a new module, structure a project, or organize code.

Analysis Mode

Trigger: User wants to analyze an existing codebase for domain boundaries, cohesion, or architectural issues.

---

Instructions

Step 1: Determine the Mode

Ask or infer from context:

• Design Mode: "create a module", "structure this project", "how should I organize...", "add a new domain"
• Analysis Mode: "analyze this code", "identify domains", "check cohesion", "review architecture", "what domains exist"

Step 2: Design Mode Workflow

When designing new modules or structuring a project:

1. Identify the Domain — Determine which business domain the code belongs to. Read references/ddd-strategic-design.md for DDD theory if needed.

2. Classify the Domain — Is it Core (competitive advantage), Supporting (essential but not differentiating), or Generic (common functionality)?

3. Define the Module Structure — Apply the layered architecture from references/architecture-guidelines.md:

   module-name/
   ├── business/        # Business logic, services, use cases, models
   ├── api/             # REST/GraphQL/gRPC handlers, DTOs
   ├── data/            # Models, repositories, migrations
   ├── async/           # Queue producers/consumers (optional)
   └── integration/     # External service providers (optional)
   

4. Apply Feature Folders (if module is complex) — When the module has 5+ services, use vertical slices. Read references/feature-folders-guidelines.md for the decision tree and rules:

   • Each feature folder is JUST a folder (not a separate module/deployment unit)
   • Single module definition registers ALL components
   • Use shared/ only for code used by 3+ features

5. Define Cross-Module Communication — Use the Public API Provider pattern from references/modular-architecture-principles.md:

   • Define interfaces in shared location
   • Implement in the owning module
   • Inject interfaces, never concrete implementations across modules

6. Apply Naming Conventions — Choose consistent naming based on language:

   • kebab-case (JavaScript/TypeScript/Ruby)
   • snake_case (Python/Go)
   • PascalCase (Java/C#)

7. Present the Structure — Show the complete folder tree with explanations for each decision.

Step 3: Analysis Mode Workflow

When analyzing an existing codebase:

1. Extract Concepts — Scan for entities, services, use cases, and controllers/handlers. Read references/domain-identification-guidelines.md for the full methodology.

2. Group by Ubiquitous Language — Cluster concepts by business vocabulary (e.g., subscription/plan/invoice = Billing, movie/video/episode = Content).

3. Identify Domains and Subdomains — Map clusters to domains. Classify each subdomain as Core, Supporting, or Generic.

4. Measure Cohesion — Score each domain using the 4 metrics:

   • Linguistic Cohesion (0-3): Shared vocabulary
   • Usage Cohesion (0-3): Concepts used together
   • Data Cohesion (0-2): Entity relationships
   • Change Cohesion (0-2): Files changed together
   • Total: X/10 (8-10 High, 5-7 Medium, 0-4 Low)

5. Detect Low Cohesion Issues — Check for:

   • Linguistic mismatch (different vocabularies in same module)
   • Cross-domain tight coupling (direct service imports between domains)
   • Mixed responsibilities (one service handling multiple domains)
   • Generic concepts in Core Domain
   • Unclear boundaries

6. Generate Report — Produce:

   • Domain Map (domains, subdomains, types, cohesion scores)
   • Cohesion Matrix (cross-domain relationships)
   • Low Cohesion Issues (with prioritized recommendations)
   • Read references/domain-identification-example.md for a complete worked example.

Step 4: Validate Against Principles

For both modes, validate the architecture against the 10 Modular Architecture Principles from references/modular-architecture-principles.md:

1. Well-Defined Boundaries — No internal details exposed
2. Composability — Modules work independently or together
3. Independence — No tight coupling, interface-based communication
4. Individual Scale — Each module scales based on its needs
5. Explicit Communication — All inter-module contracts are explicit
6. Replaceability — Modules swappable behind interfaces
7. Deployment Independence — No hard-coded deployment assumptions
8. State Isolation — Each module owns its database/schema
9. Testability — Each module testable in isolation
10. Simplicity — Minimum complexity for current needs

---

Key Architectural Rules

These rules apply universally regardless of mode:

1. Domain-based organization, not technical layers — Organize by billing/, content/, identity/, NOT by controllers/, services/, models/.

2. Business logic independent of frameworks — The business layer has no framework imports.

3. Repository Pattern for all data access — Never access the database directly from services.

4. Lean Controllers/Handlers — Handlers only handle request/response, delegate to services or use cases.

5. Use Cases are optional — Only for complex orchestration across multiple services. Simple operations use services directly.

6. Cross-module communication via interfaces — Never import another module's internal services. Use the Public API Provider pattern.

7. Feature Folders are just folders — NOT separate deployment units. One module definition per domain.

8. shared/ requires 3+ consumers — Don't prematurely abstract. Wait for a 3rd usage before moving to shared.

9. State isolation — Each module owns its database schema. No shared tables between modules.

10. Evolutionary design — Start modular monolith, extract microservices only when proven necessary.

---

Reference Files

Load these on demand based on what the task requires:

| File | When to Load | |------|-------------| | references/architecture-guidelines.md | When designing module structure, layers, naming conventions, or folder organization | | references/modular-architecture-principles.md | When validating architecture, defining cross-module communication, or checking principles | | references/feature-folders-guidelines.md | When a module is complex (5+ services) and needs vertical slice organization | | references/ddd-strategic-design.md | When identifying domains, defining bounded contexts, or understanding DDD theory | | references/domain-identification-guidelines.md | When analyzing an existing codebase for domain boundaries and cohesion | | references/domain-identification-example.md | When you need a complete worked example of domain analysis |

---

Examples

Example 1: Design a New Module

User says: "I need to create a notifications module"

Actions:

1. Classify: Notifications is typically a Generic/Supporting subdomain
2. Design the structure:

   notifications/
   ├── module-definition.*
   ├── business/
   │   ├── services/
   │   │   └── notification-service.*
   │   ├── models/
   │   │   └── notification.*
   │   └── enums/
   │       └── notification-channel-enum.*
   ├── api/
   │   └── rest/
   │       └── handlers/
   │           └── notification-handler.*
   ├── data/
   │   ├── models/
   │   │   └── notification.*
   │   └── repositories/
   │       └── notification-repository.*
   └── integration/
       └── providers/
           ├── email-provider.*
           └── sms-provider.*
   

3. Define public API interface for other modules to send notifications
4. No feature folders needed (simple module)

Example 2: Analyze a Codebase

User says: "Analyze this codebase and identify the domains"

Actions:

1. Scan the codebase for entities, services, use cases, handlers
2. Group by business vocabulary
3. Produce domain map with cohesion scores
4. Identify cross-domain coupling issues
5. Recommend improvements with priority levels

Example 3: Restructure with Feature Folders

User says: "My billing module has 12 services, how do I organize it?"

Actions:

1. Read references/feature-folders-guidelines.md
2. Apply decision tree to each service
3. Group into features: subscription/, invoice/, credit/, payment/
4. Move shared utilities to billing/shared/
5. Keep SINGLE module definition registering all components

---

Troubleshooting

Problem: Circular dependencies between modules

Cause: Direct service imports between modules instead of interfaces. Solution: Use Public API Provider pattern. Define interface in shared, implement in owning module.

Problem: Unclear which domain a concept belongs to

Cause: The concept may span multiple domains or the boundary is wrong. Solution: Check the Ubiquitous Language — which domain's vocabulary does it use? If ambiguous, it may need to be split or placed at a domain boundary with clear ownership.

Problem: Module too large and hard to navigate

Cause: Domain has grown without internal organization. Solution: Apply Feature Folders (vertical slices) within the module. NOT separate modules — just folders for organization.