# Bounded Context Canvas: [Context name]

> Design record for a single bounded context: its name, purpose, strategic
> classification, domain roles, inbound and outbound communication,
> ubiquitous language, business decisions, assumptions, verification
> metrics and open questions. The sections follow the Bounded Context
> Canvas V5 by the DDD Crew (CC BY-SA 4.0), which builds on Domain-Driven
> Design as described by Eric Evans. Replace every `[bracketed]` value and
> every row marked *Example*. Worked examples use a parcel delivery
> company's "Shipment Scheduling" context.

<!--
Guidance: How to use this template
- Fill the name and purpose first and get the team to agree on them. The
  remaining sections can be filled in any order: outside-in (start with
  inbound communication) or inside-out (start with business decisions).
- Use the canvas in a workshop, then keep this file next to the code of the
  context (for example `docs/context/shipment-scheduling.md`).
- When a section cannot be filled, do not guess: write the gap in section 11
  (Open questions) and run another modelling session (EventStorming, domain
  storytelling, example mapping) to find the answer.
- Revisit the canvas when a new collaborator appears, when the interface
  grows, or when a verification metric crosses its threshold.
-->

| Field | Value |
|---|---|
| Context name | [Shipment Scheduling] |
| Canvas version | [0.1] |
| Status | [Exploring / Agreed / Implemented / Under review] |
| Owning team | [@team-delivery-planning] |
| Domain / subdomain | [Last-mile delivery / Scheduling] |
| Workshop date | YYYY-MM-DD |
| Facilitator | [@facilitator] |
| Related documents | [Context map link], [EventStorming summary link], [ADR links] |
| Last updated | YYYY-MM-DD |

## 1. Name

<!-- Guidance: A name that domain experts recognise and use. Avoid technical names (service, manager, engine) and organisation names that change with re-orgs. If the team cannot agree on a name, the boundary is probably unclear. -->

**Name:** [Shipment Scheduling]

**Alternative names considered and rejected:**

| Candidate name | Why rejected |
|---|---|
| *Example:* Delivery Service | Technical name; says nothing about the responsibility |
| *Example:* Routing | Route optimisation is a separate, generic capability bought from a vendor |
| [Candidate] | [Reason] |

## 2. Purpose

<!-- Guidance: Two to four sentences in business language. Why does the context exist, what does it do, and for whom? No technology, no database names. Mistake: listing every feature instead of the reason the context exists. -->

[Purpose statement. *Example:* Shipment Scheduling decides when each parcel
will be delivered and commits that promise to the customer. It turns
accepted shipments into delivery slots that respect depot capacity, driver
shifts and customer preferences, and it re-plans when reality changes.
Customers, merchants and depot planners rely on it for a delivery date they
can trust.]

**Key actors who get value:** [Recipients, merchants, depot planners]

## 3. Strategic classification

<!-- Guidance: Three independent questions: how important is the context to the business (domain), what role does it play in the business model, and how evolved is the concept in the market. The answers drive build-versus-buy and where to put the most skilled people. -->

| Dimension | Options | Choice | Rationale |
|---|---|---|---|
| Domain importance | Core / Supporting / Generic | *Example:* Core | Reliable delivery promises are the main reason merchants choose us over competitors |
| Business model role | Revenue generator / Engagement creator / Compliance enforcer | *Example:* Revenue generator | Premium "named-day" delivery is sold per parcel |
| Evolution | Genesis / Custom built / Product / Commodity | *Example:* Custom built | Competitors build their own; no product fits depot-level capacity rules |

**Implication for investment:** [*Example:* Build in-house with the most
experienced team; buy route optimisation (generic) as a product.]

## 4. Domain roles

<!-- Guidance: Characterise the behaviour of the context. Common roles: specification (defines rules others execute), execution (runs a workflow), analysis (turns data into insight), gateway (translates to an external system), draft (work in progress that is later published), enforcer (applies policy). A context playing many roles may need splitting. -->

| Role | Applies? | Evidence |
|---|---|---|
| Execution context | *Example:* Yes | Runs the scheduling workflow for each accepted shipment |
| Specification context | *Example:* Partly | Defines slot rules that Depot Operations follows |
| Analysis context | *Example:* No | Capacity forecasting lives in Network Planning |
| Gateway context | *Example:* No | Carrier integrations live in Partner Gateway |
| [Role] | [Yes / No / Partly] | [Evidence] |

## 5. Inbound communication

<!-- Guidance: Messages that other collaborators send to this context. Classify each as a command (request to do something), a query (request for information) or an event (notification that something happened). The word message is not tied to technology: an HTTP POST from a form is a command. Organise rows by collaborator, in the order the use case runs. -->

| ID | Collaborator | Collaborator type | Message | Message type | Relationship type | Notes |
|---|---|---|---|---|---|---|
| IN-01 | *Example:* Shipment Intake | Bounded context | `ShipmentAccepted` | Event | Customer-supplier (we are downstream) | Triggers initial scheduling |
| IN-02 | *Example:* Recipient web app | Frontend | `ChooseDeliveryDay` | Command | Owned UI | Recipient picks one of three offered days |
| IN-03 | *Example:* Merchant portal | Frontend | `GetPromisedDate` | Query | Open host service | p95 latency 150 ms |
| IN-04 | *Example:* Depot Operations | Bounded context | `DepotCapacityChanged` | Event | Partnership | Sent when a depot loses vans or staff |
| [IN-NN] | [Collaborator] | [Context / Frontend / External system / User] | [Message] | [Command / Query / Event] | [Relationship] | [Notes] |

**Use case swimlane (optional):** describe the main flow as
*message in -> decisions made -> message out*. *Example:*
`ShipmentAccepted -> choose earliest slot with capacity and promise rules -> DeliveryPromised`.

## 6. Outbound communication

<!-- Guidance: Messages this context initiates towards other collaborators. Same classification as inbound. Watch for queries to many contexts during one command: it suggests the context depends on data it should own or receive by event. -->

| ID | Collaborator | Collaborator type | Message | Message type | Relationship type | Notes |
|---|---|---|---|---|---|---|
| OUT-01 | *Example:* Notifications | Bounded context | `DeliveryPromised` | Event | Published language | Recipient receives SMS and email |
| OUT-02 | *Example:* Route Optimisation (vendor) | External system | `OptimiseRoutes` | Command | Anticorruption layer | Nightly batch per depot |
| OUT-03 | *Example:* Depot Operations | Bounded context | `DeliveryRescheduled` | Event | Partnership | Moves parcel to another van load |
| OUT-04 | *Example:* Billing | Bounded context | `NamedDayServiceDelivered` | Event | Customer-supplier (we are upstream) | Charges the premium fee |
| [OUT-NN] | [Collaborator] | [Type] | [Message] | [Type] | [Relationship] | [Notes] |

## 7. Ubiquitous language

<!-- Guidance: The key terms inside this context and what they mean here. A term can mean something different in another context; that is expected. Keep the full glossary in a separate Ubiquitous Language document and list only the ten or so most important terms here. -->

| Term | Meaning in this context |
|---|---|
| *Example:* Delivery promise | The date and time window the customer was told, which we commit to meet |
| *Example:* Slot | A depot's capacity for one day and one time window, measured in parcel stops |
| *Example:* Reschedule | Moving a promise to a new slot, with the recipient informed before the original window starts |
| *Example:* Named day | A paid service where the recipient chooses the day; failure triggers a refund |
| [Term] | [Meaning] |

## 8. Business decisions

<!-- Guidance: The key rules and policies the context enforces. Write them as rules a domain expert would sign off, with an ID so tests and code can reference them. Mistake: listing technical validations (field is not null) instead of business rules. -->

| ID | Rule or policy | Source | Example |
|---|---|---|---|
| BR-01 | *Example:* A slot may be booked up to 95% of its capacity; the last 5% is reserved for rescheduled parcels | Head of Operations | Depot with 400 stops accepts 380 new promises |
| BR-02 | *Example:* A promise may be rescheduled at most twice before escalation to a planner | Customer service policy | Third reschedule creates a planner task |
| BR-03 | *Example:* Named-day promises are never moved by automatic rescheduling | Commercial terms | Capacity loss moves standard parcels first |
| BR-04 | *Example:* Promises are offered only for days when the recipient's address is serviceable | Network rules | Island postcodes receive Tuesday and Friday only |
| [BR-NN] | [Rule] | [Owner or document] | [Concrete example] |

## 9. Assumptions

<!-- Guidance: Design decisions made without full knowledge. Make them explicit so they can be tested and revisited. Each assumption should have a way to find out whether it is true. -->

| ID | Assumption | Impact if wrong | How we will validate | Status |
|---|---|---|---|---|
| AS-01 | *Example:* Depot capacity changes at most a few times a day | Event volume and recalculation cost rise sharply | Count `DepotCapacityChanged` for four weeks | Open |
| AS-02 | *Example:* Route optimisation remains a generic product we can buy | We would need a team to build it | Vendor review in Q3 | Open |
| AS-03 | *Example:* Recipients accept a promise window of two hours | Need finer slots and a new capacity model | Survey plus A/B test on 5% of traffic | Validated YYYY-MM-DD |
| [AS-NN] | [Assumption] | [Impact] | [Validation] | [Open / Validated / Invalidated] |

## 10. Verification metrics

<!-- Guidance: Metrics that tell you whether the boundary is a good fit. Collect them from CI/CD, the issue tracker and production. A boundary that is wrong shows up as many cross-context changes, chatty interfaces or frequent coordination between teams. -->

| Metric | Source | Target | Current | Signal if breached |
|---|---|---|---|---|
| *Example:* Share of changes that also touch another context's code | Version control | < 10% of merged pull requests | [Value] | Boundary may be in the wrong place |
| *Example:* Synchronous calls to other contexts per scheduling command | Tracing | <= 2 | [Value] | Context lacks data it should own |
| *Example:* Releases blocked by another team | Issue tracker | 0 per month | [Value] | Coupling at team level |
| *Example:* Promises kept (delivered in promised window) | Production | >= 97% | [Value] | Business decisions or model need review |
| [Metric] | [Source] | [Target] | [Value] | [Signal] |

## 11. Open questions

<!-- Guidance: Questions nobody in the room could answer. Give each one an owner and a date so it does not get lost. The number of open questions is a visible measure of how certain the team is about the design. -->

| ID | Question | Owner | Needed by | Answer |
|---|---|---|---|---|
| OQ-01 | *Example:* Should rescheduling for weather events be decided here or in Network Planning? | @domain-expert | YYYY-MM-DD | [Answer when known] |
| OQ-02 | *Example:* Do merchants need to cancel a promise, or only the recipient? | @product-owner | YYYY-MM-DD | [Answer] |
| [OQ-NN] | [Question] | [@owner] | YYYY-MM-DD | [Answer] |

## 12. Design review checklist

<!-- Guidance: Use these questions to challenge the canvas before agreeing on it. -->

- [ ] The purpose is written in business language and fits in four sentences.
- [ ] Message names are coherent with each other and with the purpose.
- [ ] Each message type is the right one (a command that should be an event, or the reverse, is flagged).
- [ ] The interface is not too big: [N] distinct message types in, [N] out.
- [ ] No message exposes internal model details that collaborators should not depend on.
- [ ] No message obviously belongs to another context.
- [ ] Every relationship type matches the context map.
- [ ] Every assumption has a validation plan and every open question has an owner.

## Standard and licence note

Structure adapted from the Bounded Context Canvas (V5) by the DDD Crew
(Nick Tune and contributors), https://github.com/ddd-crew/bounded-context-canvas.
The repository's licence file states Creative Commons Attribution-ShareAlike
4.0 International (CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/);
its README shows a CC BY 4.0 badge, so this adaptation follows the stricter
of the two. The adapted structure in this template is shared under
CC BY-SA 4.0. Concepts of bounded contexts, ubiquitous language and context
relationships come from Domain-Driven Design by Eric Evans. All explanatory
text and examples are original to this collection.