Bounded contexts and subdomains

Define bounded contexts in SpecsGraph with a key, purpose, owning team and subdomain type (core, supporting or generic), and learn when to split or merge them.

What a bounded context is

A bounded context is a part of your system inside which words and rules have one meaning. Inside Orders, an order is what a Customer checks out. Inside Fulfilment, the same word can mean a batch of items a warehouse picks and ships. Each context owns its own model and its own slice of the glossary, and the edges between contexts show where those models meet.

In SpecsGraph, contexts are the top-level nodes on the system map. Every requirement, service and context-scoped glossary term belongs to exactly one context. The idea comes from Domain-Driven Design; Domain-driven and behavior-driven foundations covers the background.

Context fields

Field	What it holds	Orders example
Name	The name people use in conversation.	Orders
Key	Short code of 2 to 5 capital letters, used as the prefix of requirement IDs.	`ORD`
Purpose	One or two sentences on what the context is responsible for, and what it is not.	Turns a cart into a confirmed order and holds stock while the Customer pays. Does not ship anything.
Owning team	The team responsible for the context. Reviewers use it to see who should look at a change here.	Checkout team
Subdomain type	Core, supporting or generic.	Core

The purpose is the field people skip and later regret. A good purpose marks the boundary, including what the context deliberately leaves to its neighbors. Agents read it too, and a clear boundary is what stops them from putting a shipping rule into Orders.

Northwind uses these keys: IDN for Identity, BIL for Billing, CAT for Catalog, ORD for Orders, FUL for Fulfilment, NTF for Notifications and ANL for Analytics.

Classify the subdomain

Each context is classified by the kind of subdomain it serves. The classification tells reviewers and agents where the business wins or loses, and where a standard solution is fine.

Type	Meaning	Northwind
Core	What sets the business apart. It deserves careful modeling, your most experienced people and the closest review.	Orders, Catalog
Supporting	Specific to your business but not a differentiator. Build it simply and keep it correct.	Billing, Fulfilment, Analytics
Generic	A problem every business has, already solved elsewhere. Buy it, use a library or follow a standard.	Identity, Notifications

Northwind treats Orders as core because reserving stock at checkout (ORD-12) is how it avoids overselling limited product runs. Billing is supporting: the card payment itself goes through an external payment provider, but the rule that capture waits for a reservation (BIL-04) is Northwind's own.

In SpecsGraph a subdomain is not a node of its own: each context records the type of subdomain it serves. When one subdomain spans several contexts, give each of them the same type and name the subdomain in their purposes.

Tip

Classification can change. If a generic context starts collecting rules that only your company has, reclassify it in a proposal and record the reason in the decision log.

Services inside a context

A service is a unit inside a context that implements part of its behavior: a deployable app, a module or a background worker. Services give requirements a more precise home and add one more zoom level to the map.

The Orders context has two services. Checkout holds ORD-12 and ORD-13, the reservation rules. Order history holds the requirements for listing and viewing past orders. A requirement always belongs to a context and optionally to one service, so leave the service empty while the design is still open.

When to split or merge

Contexts are not fixed. Change them through a structure proposal when the language or the ownership tells you to.

Signs a context should split

One term needs two definitions inside it, for example slot meaning a delivery window in one place and a warehouse shelf position in another.
Two teams keep reviewing each other's changes in it.
Its requirements fall into groups that never link to each other.

Signs two contexts should merge

Almost every proposal touches both.
They use the same glossary terms with the same definitions.
A shared kernel between them keeps growing.

Agents can draft these changes with propose_structure_change. The proposal lists every service, requirement, term and relationship that moves, so reviewers see the full effect before they approve it.

To remove a context, move or retire its requirements in the same structure proposal, so reviewers can see where every rule ends up.

Renaming keeps IDs stable

Renaming a context changes its display name only. The key stays the same, so requirement IDs keep working, along with every commit message, test name and code comment that quotes one. If Northwind renames Orders to Ordering, ORD-12 is still ORD-12, and its file keeps its path; see Spec files in your repository.

Requirements that move to another context during a split keep their IDs as well, and their files move to the new context's folder. The prefix records where a requirement was first written, not where it lives today. Choose keys with care: they end up in commit messages, test names and code for years.

Next steps

Domain glossary to give each context its own vocabulary.
Requirements and scenarios to fill a context with rules.
Context relationships to connect contexts on the map.