Step 6: Understand and structure the domain

What you get from this step

You end this step with four things:

A shared vocabulary. Developers, domain experts and other stakeholders use the same words for the same things. It is written down as the glossary, which is arc42 section 12. See arc42 Glossary.
A list of bounded contexts. A bounded context is a boundary inside which one domain model and one vocabulary apply.
A context map. It shows how the contexts, and the external systems around them, relate.
A sketch of the important data. This is a conceptual data model: entities, attributes and relationships, with no database details.

The contexts and the data sketch also give you a first set of building blocks for arc42 section 5.

What you need first

Access to people who know the business. They are the domain experts. You need their own words and their corrections.
A rough picture of what the system does and which external systems it talks to.
One person who will own the glossary. Publishing the conceptual data model suggests a role such as the product owner or project manager.

If something is missing

No domain experts available. Ask whoever knows the business best. Mark every term and boundary they give you as unconfirmed. Write down the open questions. Many open questions signal high uncertainty (see Bounded Context Canvas).
No list of processes or stories. Collect them now, as in step 2 below. Domain Storytelling is one way to do it.
No glossary yet. Start with an empty list and fill it as you go.
Experts disagree on a word. Do not force one meaning. Note both meanings and keep them apart. Step 3 shows how.

How to do it

Name an owner for the glossary. Pick one person. The glossary must be updated as the team’s understanding changes. See arc42 Glossary.
Let experts tell how they work. In Domain Storytelling, experts describe their work and the group draws it as actors, work objects and activities. For each story, state whether it is as-is or to-be and whether it is an overview or detailed. Label the drawings with the experts’ own terms.
Collect terms and find the ones with several meanings. Words such as “Customer” or “Product” often mean different things to different groups. Do not merge them. Write each meaning down. See Business Domain Understanding and Ubiquitous Language. A ubiquitous language is one shared vocabulary, and its terms hold only inside one bounded context.
Split the domain into bounded contexts. Where meanings truly differ, put each meaning into its own context. Boundaries you read from stories are indications, not proof. For each context:
- Agree on a name.
- Write its purpose in a few sentences of business language.
- Classify it as core, supporting or generic.
- Define differing terms per context.
Bounded Context Canvas gives a template. Also think about which team will own each context. See Reflecting the Business Domain in the Architecture.
Draw a context map. Show the contexts and the external systems. Explain every arrow, including which side is upstream (provides) and which is downstream (consumes). Label each relationship with a named pattern. See Context Map. Events that cross context boundaries are integration events and should be asynchronous. See Domain Event.
Sketch the important data. For each context, list the entities and their attributes. State relationships with cardinality and whether they are mandatory or optional. Add the business rules. Leave out data types, tables and indexes. See Conceptual Data Model and Conceptual data model building method.
- An entity has an identity that stays the same while its attributes change.
- A value object has no identity and is immutable.
- If an entity appears in several contexts, each context keeps only the attributes it needs.
- Where objects must stay consistent together, group them in an aggregate with one root. Other aggregates refer to it by identity only.
Check the model with stakeholders. Record the gaps you find. Only entities and relationships, in business terms, belong in the diagram. See Conceptual Data Model Preparation for Logical and Physical Models.
Derive building blocks for section 5. Group concepts that belong together. Mark external systems clearly. Put them behind a translating wrapper. See Deriving System Components from the Domain Model.
Publish and keep updating. Make the glossary and the model available to everyone. Revise them as you learn. See Publishing the conceptual data model and Iterative Domain Modeling.

Example: ClinicBook

ClinicBook is a fictional online booking system for 40 small medical practices. The team ran a short story session with front-desk staff. Everyone used the word “appointment”. They meant different things:

Patient: a time I have reserved.
Practice staff: a block in my calendar.
Practice-management software: a record in the vendor’s own format. It differs by vendor.

The team did not pick one meaning. It wrote all three into the glossary and split the domain into contexts.

Proposed bounded contexts (all are drafts, to be confirmed by the experts):

Context	Purpose	Class
Booking	Patients find, book, move and cancel appointments.	Core
Practice Calendar	Staff manage opening times and free slots.	Core
Reminders	Remind patients of appointments by SMS and e-mail.	Generic
Practice System Integration	Exchange appointment data with each vendor’s software.	Supporting

Context map, in short:

Booking and Practice Calendar exchange availability.
Booking publishes integration events, such as “AppointmentBooked” and “AppointmentCanceled”. Events are named in the past tense. Reminders consumes them asynchronously.
The vendors’ practice-management systems are external. Practice System Integration wraps them, so vendor formats do not leak into the other contexts.
Each arrow in the map is labeled upstream or downstream and with a named pattern.

Data sketch:

Entities:
- Patient
- Practice
- Calendar
- Appointment
- Reminder
Value object: a time range (start and end), which is replaced rather than edited.
Appointment life cycle: requested, booked, moved, canceled.
Rule: a slot holds at most one active appointment.
Aggregate: Calendar is the root. It guards the double-booking rule, because slot and appointment must change together. Appointments refer to the patient by identity only.
Privacy: Reminders keeps only the contact channel and the appointment time. It does not keep health details, because a context holds only the attributes it needs.

Open questions the team wrote down:

Which vendor formats must the integration context support first?
Can a small team own these four contexts? If one team owns several, are they related enough?
Do the morning peaks justify a separate read model for availability search in the Booking context only? That is a later decision. See Command Query Responsibility Segregation.

The team added the terms (Appointment in each meaning, Slot, Practice, Reminder) to section 12. It used the contexts and the external systems as the starting point for the section 5 building blocks.

Done when

The glossary lists the key terms, has a named owner, and shows terms with several meanings per context. See arc42 Glossary.
Each bounded context has an agreed name, a business-language purpose and a core, supporting or generic class. See Bounded Context Canvas.
A context map shows all contexts and external systems, with explained arrows and named patterns. See Context Map.
The conceptual data sketch has entities, attributes, relationships with cardinality, and business rules, but no database details. See Conceptual Data Model.
Stakeholders have checked the sketch and the gaps are recorded. See Conceptual Data Model Preparation for Logical and Physical Models.
Building blocks for section 5 follow the contexts, with external systems marked and wrapped. See Deriving System Components from the Domain Model.