Bounded Contexts Analyzer

Overview

This skill analyzes PHP DDD projects for bounded context boundary issues, cross-context coupling, and context mapping violations.

Bounded Context Concepts

| Concept | Definition | Violation Indicator | |---------|------------|---------------------| | Bounded Context | Explicit boundary with its own domain model | Missing namespace separation | | Ubiquitous Language | Consistent terminology within context | Same term, different meanings | | Context Map | Relationships between contexts | Unclear dependencies | | Anti-Corruption Layer | Translation between contexts | Direct foreign model usage | | Shared Kernel | Deliberately shared code | Unintentional sharing | | Published Language | Public API contracts | Breaking changes |

Detection Patterns

Phase 1: Context Discovery

# Identify bounded contexts from directory structure
Glob: **/src/**/Domain/*
Glob: **/src/**/Context/*
Glob: **/src/**/Bounded/*
Glob: **/src/**/Module/*

# Namespace-based contexts
Grep: "namespace.*\\\\Domain\\\\|namespace.*\\\\Context\\\\" --glob "**/*.php"

# Composer autoload namespaces
Read: composer.json (check autoload paths for context namespaces)

Context Indicators:

Top-level namespace under src/ (e.g., Order, User, Payment)
Explicit Domain/ subfolder per context
BoundedContext/ or Context/ folder structure

Phase 2: Cross-Context Coupling Detection

Direct Cross-Context Imports

# Find cross-context imports (most critical)
# Pattern: Context A importing from Context B's Domain layer

# Order context importing User domain
Grep: "use Order\\\\.*\\\\Domain" --glob "**/User/**/*.php"
Grep: "use User\\\\.*\\\\Domain" --glob "**/Order/**/*.php"

# General pattern: Domain layer importing another Domain
Grep: "use [A-Z][a-z]+\\\\Domain\\\\" --glob "**/Domain/**/*.php"

# Direct entity references across contexts
Grep: "use.*\\\\Entity\\\\(?!.*\\\\self)" --glob "**/Domain/**/*.php"

Foreign Aggregate References

# Aggregates referencing foreign entities directly
Grep: "private.*[A-Z][a-z]+Entity\|private readonly [A-Z][a-z]+" --glob "**/Aggregate/**/*.php"

# Should use ID references only
# Good: private UserId $userId
# Bad: private User $user (from another context)

# Detect direct object references vs ID references
Grep: "\\$user[^I]|\\$order[^I]|\\$customer[^I]" --glob "**/Domain/**/*.php"

Shared Repository Usage

# Repository from one context used in another
Grep: "UserRepositoryInterface" --glob "**/Order/**/*.php"
Grep: "OrderRepositoryInterface" --glob "**/User/**/*.php"

# Generic repository pattern violations
Grep: "RepositoryInterface" --glob "**/*.php"
# Check if implementations span contexts

Phase 3: Shared Kernel Analysis

# Identify potential shared kernel (common code between contexts)
Glob: **/Shared/**/*.php
Glob: **/Common/**/*.php
Glob: **/Core/**/*.php
Glob: **/SharedKernel/**/*.php

# Find duplicated Value Objects across contexts
# Same class name in multiple contexts
Glob: **/Domain/**/Email.php
Glob: **/Domain/**/Money.php
Glob: **/Domain/**/Address.php

# Shared events
Grep: "class.*Event.*implements|extends.*Event" --glob "**/Shared/**/*.php"

Shared Kernel Rules:

Must be explicitly designated
Minimal and stable
Changes require agreement from all context owners
Should contain only Value Objects, not Entities

Phase 4: Context Map Relationships

Upstream/Downstream Detection

# Event publishers (upstream)
Grep: "EventDispatcher|MessageBus|publish\(" --glob "**/Domain/**/*.php"
Grep: "class.*Event\s*\{|final readonly class.*Event" --glob "**/Domain/**/*.php"

# Event subscribers (downstream)
Grep: "EventSubscriber|MessageHandler|Listener" --glob "**/*.php"
Grep: "function __invoke\(.*Event" --glob "**/*.php"

# Check which context publishes and which subscribes

Customer/Supplier Relationships

# API clients (customer role)
Grep: "ApiClient|HttpClient|RestClient" --glob "**/Infrastructure/**/*.php"

# API providers (supplier role)
Grep: "Controller|Action|Endpoint" --glob "**/Presentation/**/*.php"

Anti-Corruption Layer Detection

# ACL presence
Glob: **/AntiCorruption/**/*.php
Glob: **/ACL/**/*.php
Glob: **/Adapter/**/*.php
Glob: **/Translator/**/*.php

# Missing ACL (direct external model usage)
Grep: "use External\\\\|use ThirdParty\\\\|use Legacy\\\\" --glob "**/Domain/**/*.php"

Phase 5: Ubiquitous Language Analysis

# Find same term with different meanings
# Example: "Account" in User context vs Payment context

# Find class with same name in different contexts
Glob: **/User/**/Account.php
Glob: **/Payment/**/Account.php
Glob: **/Billing/**/Account.php

# Find similar entity names
Glob: **/Domain/**/User.php
Glob: **/Domain/**/Customer.php
Glob: **/Domain/**/Client.php

# Inconsistent naming
Grep: "class Order|class Purchase|class Sale" --glob "**/Domain/**/*.php"

Report Format

# Bounded Context Analysis Report

## Context Map

```mermaid
graph TB
    subgraph "Order Context"
        O_Domain[Domain]
        O_App[Application]
    end

    subgraph "User Context"
        U_Domain[Domain]
        U_App[Application]
    end

    subgraph "Payment Context"
        P_Domain[Domain]
        P_App[Application]
    end

    subgraph "Shared Kernel"
        SK[Money, Currency]
    end

    O_Domain -->|"uses ID only"| U_Domain
    O_Domain -->|"publishes events"| P_Domain
    O_Domain --> SK
    U_Domain --> SK
    P_Domain --> SK

Detected Contexts

| Context | Location | Entities | Events | Dependencies | |---------|----------|----------|--------|--------------| | Order | src/Order/ | 5 | 8 | User (ID), Payment (event) | | User | src/User/ | 3 | 4 | None | | Payment | src/Payment/ | 4 | 6 | Order (event) | | Shared | src/Shared/ | 0 | 0 | All contexts |

Critical Issues

BC-001: Cross-Context Entity Reference

File: src/Order/Domain/Entity/Order.php:15
Issue: Direct reference to User entity instead of UserId
Code: private User $user (from User context)
Expected: private UserId $userId
Impact: Tight coupling, breaks context isolation
Refactoring: Replace with ID reference, use ACL if needed
Skills: acc-create-value-object (for UserId), acc-create-anti-corruption-layer

BC-002: Missing Anti-Corruption Layer

File: src/Payment/Infrastructure/Gateway/StripeGateway.php
Issue: Stripe models used directly in domain
Code: use Stripe\PaymentIntent;
Impact: External API changes affect domain
Refactoring: Create PaymentIntent adapter/translator
Skills: acc-create-anti-corruption-layer

BC-003: Unintended Shared Kernel

Files:
- src/Order/Domain/ValueObject/Address.php
- src/User/Domain/ValueObject/Address.php
Issue: Duplicated Address VO without explicit sharing
Impact: Inconsistent behavior, maintenance burden
Refactoring: Either consolidate to Shared Kernel or differentiate
Skills: acc-create-value-object

Warning Issues

BC-004: Ambiguous Ubiquitous Language

Context 1: src/User/ uses Account for user profile
Context 2: src/Payment/ uses Account for financial account
Issue: Same term, different meanings
Refactoring: Rename to UserProfile and PaymentAccount

BC-005: Missing Published Language

Context: Order
Issue: No explicit contract for inter-context communication
Events published: 8
Documented: 0
Refactoring: Create event schema documentation

BC-006: Upstream Without Events

Context: User (upstream)
Downstream: Order, Payment (via direct queries)
Issue: Downstream contexts query User directly
Refactoring: User should publish events, downstreams react

Context Relationship Matrix

| From \ To | Order | User | Payment | Shared | |-----------|-------|------|---------|--------| | Order | - | ID ref | Events | Uses | | User | - | - | - | Uses | | Payment | Queries | Queries | - | Uses | | Shared | - | - | - | - |

Legend:

ID ref: References only by ID (good)
Events: Async event communication (good)
Queries: Direct query (warning)
Uses: Shared kernel usage (acceptable)

Recommendations

Immediate Actions

Replace direct entity references with ID Value Objects
Add ACL for external service integrations

Short-term

Document published language (event contracts)
Consolidate or differentiate duplicated VOs

Long-term

Consider event-driven communication between contexts
Review shared kernel scope


## Context Integration Patterns

### Recommended Patterns

| Pattern | When to Use | Skills |
|---------|-------------|--------|
| ID Reference | Entity association across contexts | `acc-create-value-object` |
| Domain Events | Async communication | `acc-create-domain-event` |
| ACL | External systems, legacy | `acc-create-anti-corruption-layer` |
| Shared Kernel | Common VOs (Money, etc.) | `acc-create-value-object` |
| Published Language | Public contracts | Documentation |

### Anti-patterns

| Anti-pattern | Issue | Remediation |
|--------------|-------|-------------|
| Direct Entity Reference | Tight coupling | Use ID + resolve via query |
| Shared Entities | Ownership unclear | Split or explicit ownership |
| Cross-Context Repository | Boundary violation | Use events or ACL |
| Synchronous Cross-Context Calls | Temporal coupling | Use async events |

## Quick Analysis Commands

```bash
# Detect bounded contexts
echo "=== Bounded Contexts ===" && \
find src -maxdepth 2 -type d -name "Domain" && \
echo "=== Cross-Context Imports ===" && \
for ctx in $(find src -maxdepth 1 -type d | tail -n +2); do \
  name=$(basename $ctx); \
  grep -rn "use .*\\\\Domain\\\\" --include="*.php" "$ctx" | grep -v "use $name"; \
done && \
echo "=== Shared Kernel ===" && \
find src -type d -name "Shared" -o -name "Common" -o -name "Core"

Integration

Works with:

acc-ddd-auditor — Domain model quality
acc-structural-auditor — Layer violations
acc-ddd-generator — Generate missing components

References

"Domain-Driven Design" (Eric Evans) — Chapter 14: Context Mapping
"Implementing Domain-Driven Design" (Vaughn Vernon) — Chapter 3: Context Maps
Strategic DDD patterns documentation