# 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](https://arc.fuet.ch/concepts/documentation/arc42-glossary.md).
- A list of bounded contexts. A [bounded context](https://arc.fuet.ch/concepts/domain-driven-design/bounded-context.md) 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](https://arc.fuet.ch/concepts/data-architecture/publishing-the-conceptual-data-model.md) 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](https://arc.fuet.ch/concepts/domain-driven-design/bounded-context-canvas.md)).
- **No list of processes or stories.** Collect them now, as in step 2 below. [Domain Storytelling](https://arc.fuet.ch/concepts/domain-driven-design/domain-storytelling.md) 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

1. **Name an owner for the glossary.** Pick one person. The glossary must be updated as the team's understanding changes. See [arc42 Glossary](https://arc.fuet.ch/concepts/documentation/arc42-glossary.md).
2. **Let experts tell how they work.** In [Domain Storytelling](https://arc.fuet.ch/concepts/domain-driven-design/domain-storytelling.md), 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.
3. **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](https://arc.fuet.ch/concepts/domain-driven-design/business-domain-understanding.md) and [Ubiquitous Language](https://arc.fuet.ch/concepts/domain-driven-design/ubiquitous-language.md). A ubiquitous language is one shared vocabulary, and its terms hold only inside one bounded context.
4. **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](https://arc.fuet.ch/concepts/domain-driven-design/bounded-context-canvas.md) gives a template. Also think about which team will own each context. See [Reflecting the Business Domain in the Architecture](https://arc.fuet.ch/concepts/domain-driven-design/reflecting-the-business-domain-in-the-architecture.md).
5. **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](https://arc.fuet.ch/concepts/domain-driven-design/context-map.md). Events that cross context boundaries are integration events and should be asynchronous. See [Domain Event](https://arc.fuet.ch/concepts/domain-driven-design/domain-event.md).
6. **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](https://arc.fuet.ch/concepts/data-architecture/conceptual-data-model.md) and [Conceptual data model building method](https://arc.fuet.ch/concepts/data-architecture/conceptual-data-model-building-method.md).
   - An [entity](https://arc.fuet.ch/concepts/domain-driven-design/entity.md) has an identity that stays the same while its attributes change.
   - A [value object](https://arc.fuet.ch/concepts/domain-driven-design/value-object.md) 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](https://arc.fuet.ch/concepts/domain-driven-design/aggregate.md) with one root. Other aggregates refer to it by identity only.
7. **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](https://arc.fuet.ch/concepts/data-architecture/conceptual-data-model-preparation-for-logical-and-physical-models.md).
8. **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](https://arc.fuet.ch/concepts/domain-driven-design/deriving-system-components-from-the-domain-model.md).
9. **Publish and keep updating.** Make the glossary and the model available to everyone. Revise them as you learn. See [Publishing the conceptual data model](https://arc.fuet.ch/concepts/data-architecture/publishing-the-conceptual-data-model.md) and [Iterative Domain Modeling](https://arc.fuet.ch/concepts/domain-driven-design/evolutionary-domain-modeling.md).

## 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](https://arc.fuet.ch/concepts/data-architecture/command-query-responsibility-segregation.md).

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](https://arc.fuet.ch/concepts/documentation/arc42-glossary.md).
- Each bounded context has an agreed name, a business-language purpose and a core, supporting or generic class. See [Bounded Context Canvas](https://arc.fuet.ch/concepts/domain-driven-design/bounded-context-canvas.md).
- A context map shows all contexts and external systems, with explained arrows and named patterns. See [Context Map](https://arc.fuet.ch/concepts/domain-driven-design/context-map.md).
- The conceptual data sketch has entities, attributes, relationships with cardinality, and business rules, but no database details. See [Conceptual Data Model](https://arc.fuet.ch/concepts/data-architecture/conceptual-data-model.md).
- Stakeholders have checked the sketch and the gaps are recorded. See [Conceptual Data Model Preparation for Logical and Physical Models](https://arc.fuet.ch/concepts/data-architecture/conceptual-data-model-preparation-for-logical-and-physical-models.md).
- Building blocks for section 5 follow the contexts, with external systems marked and wrapped. See [Deriving System Components from the Domain Model](https://arc.fuet.ch/concepts/domain-driven-design/deriving-system-components-from-the-domain-model.md).

## Learn more

- [Domain-Driven Design](https://arc.fuet.ch/concepts/domain-driven-design/domain-driven-design.md)
- [Domain Model](https://arc.fuet.ch/concepts/domain-driven-design/domain-model.md)
- [Domain Storytelling](https://arc.fuet.ch/concepts/domain-driven-design/domain-storytelling.md)
- [Ubiquitous Language](https://arc.fuet.ch/concepts/domain-driven-design/ubiquitous-language.md)
- [Business Domain Understanding](https://arc.fuet.ch/concepts/domain-driven-design/business-domain-understanding.md)
- [Bounded Context](https://arc.fuet.ch/concepts/domain-driven-design/bounded-context.md)
- [Bounded Context Canvas](https://arc.fuet.ch/concepts/domain-driven-design/bounded-context-canvas.md)
- [Context Map](https://arc.fuet.ch/concepts/domain-driven-design/context-map.md)
- [Domain Event](https://arc.fuet.ch/concepts/domain-driven-design/domain-event.md)
- [Entity](https://arc.fuet.ch/concepts/domain-driven-design/entity.md)
- [Entity and Value Object](https://arc.fuet.ch/concepts/domain-driven-design/entity-vs-value-object.md)
- [Entity Life Cycle](https://arc.fuet.ch/concepts/domain-driven-design/entity-life-cycle.md)
- [Aggregate](https://arc.fuet.ch/concepts/domain-driven-design/aggregate.md)
- [Conceptual data model building method](https://arc.fuet.ch/concepts/data-architecture/conceptual-data-model-building-method.md)
- [Conceptual, Logical and Physical Data Model](https://arc.fuet.ch/concepts/data-architecture/conceptual-vs-logical-vs-physical-data-model.md)
- [Data Architecture](https://arc.fuet.ch/concepts/data-architecture/data-architecture.md)
- [Domain-Driven Design of the Data Model](https://arc.fuet.ch/concepts/domain-driven-design/domain-modeling-procedure.md)
- [Reflecting the Business Domain in the Architecture](https://arc.fuet.ch/concepts/domain-driven-design/reflecting-the-business-domain-in-the-architecture.md)
- [Command Query Responsibility Segregation](https://arc.fuet.ch/concepts/data-architecture/command-query-responsibility-segregation.md)