Bounded Contexts

Bounded Context Design for PHP Monoliths

When to Use Bounded Contexts (and When NOT to)

Bounded contexts are appropriate for complex applications with multiple business capabilities. They are not needed for every project.

| Use Bounded Contexts For | Do Not Use For | |----------------------------------------------------|---------------------------------------| | Complex business domain with multiple capabilities | Simple CRUD apps with one clear model | | Team of multiple developers owning different areas | Solo developer or small team | | Long-lived system requiring clear ownership | Prototypes, throwaway code | | Application with multiple integration surfaces | Libraries, packages, SDKs |

For libraries and packages, use standard PSR-4 namespacing to organize code. Bounded-context separation only applies when the project has multiple domain capabilities that different teams or subsystems must own independently.

System Overview

The backend north star for modular PHP applications is business-capability-first bounded contexts. Current folders, namespaces, controllers, database prefixes, and API route groups are supporting evidence, not the source of truth for ownership. This skill helps map out business boundaries and clarify cross-context integration patterns.

Numbered Workflows

1. Discovering Bounded Contexts

If evaluating whether a grouping of code should be a bounded context:

1. Identify the Capability. Does this grouping represent a distinct business capability, process, or lifecycle? If yes, it is a candidate.
2. Apply the "Not a Bounded Context" Classifier. If the grouping is primarily an infrastructure service (e.g., Search Engine), third-party integration (e.g., Salesforce), API surface, delivery channel (e.g., Email), or config mechanism, then it is not a bounded context.
3. Assign Ownership. Map the underlying business concepts to their true domain contexts (e.g., a payment webhook belongs to Billing, not a "Webhook" context).

2. Defining Cross-Context Ownership

If passing data between contexts:

1. Identify the Source Fact. The context that originates the fact (e.g., Billing for payments) remains the owner.
2. Project the Fact. If another context needs the fact (e.g., Entitlements needs to know if a user paid), it consumes the fact without taking ownership.

3. Designing the Shared Kernel

If extracting code to share across multiple contexts:

1. Evaluate Necessity. Is this concept intentionally shared to reduce coupling?
2. If it is an identity reference (UserId), a core value object (Money), or a domain event contract, place it in the Shared Kernel.
3. If it is generic utility code (e.g., array helpers), do not place it in the Shared Kernel.

Recognizing Boundary Problems in an Existing Codebase

When analyzing an established codebase, these are signals of misplaced or missing boundaries (judge against real business capabilities; do not reshuffle folders for tidiness):

• "Infrastructure" contexts. A context named after a transport or vendor — Webhooks, Email, Salesforce — instead of a business capability. Webhooks/integrations are infrastructure, not contexts; re-home them to the capability that owns the fact (e.g., a payment webhook belongs to Billing).
• Shared Kernel as a util dump. The "common" namespace holds array helpers, base classes, and generic traits rather than identity references, core value objects, or event contracts.
• Structure-by-layer, not by-capability. Code is sliced by technical layer (Controllers/, Models/, Repositories/) across the whole app rather than grouped by business capability, so a single feature's logic is scattered.
• Hidden ownership. No context map or glossary; the same term means different things in different areas, or facts are owned by the consumer rather than their source.

Boundaries

Always Do

• Always use the [Context Map Template](references/context-map-template.md) to document how contexts interact.
• Always establish clear ownership for terms using the [Glossary Template](references/glossary-template.md).
• Always treat the context map as a living document; revisit boundaries when new lifecycle behaviors emerge.

Ask First

• Ask before introducing a new bounded context; ensure it aligns with a distinct business capability.

Never Do

• Never mix infrastructure boundaries (like third-party APIs) with domain boundaries.
• Never turn the Shared Kernel into a generic "utilities dump" or "common bucket".
• Never skim DDD as just a directory structure. Bounded contexts are defined by a ubiquitous language and business capability, not by folders or namespaces.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: garrettw
• Source: garrettw/php-arch-skills
• License: MPL-2.0

Install and usage instructions live in the source repository linked above.