# Context Map: [Domain or product area]

> Map of the bounded contexts in one domain and the relationships between
> them: who depends on whom, which Domain-Driven Design integration pattern
> governs each relationship, how the teams cooperate and how the map should
> evolve. Based on the context mapping patterns of Domain-Driven Design
> (Eric Evans) and common practice. Replace every `[bracketed]` value and
> every row marked *Example*. Worked examples use an online grocery retailer.

<!--
Guidance: How to use this template
- Map what exists today first (the "as-is" map), including the messy parts.
  A context map that shows only the intended design hides the problems it is
  meant to expose.
- Every relationship has a direction: upstream contexts influence
  downstream ones. Record the direction before choosing a pattern.
- Patterns describe both the technical integration and the team
  relationship. A shared kernel without close team cooperation will fail.
- Write the target ("to-be") map in section 7 and link each change to an
  ADR or roadmap item.
-->

| Field | Value |
|---|---|
| Domain / scope | [Online grocery: ordering, fulfilment, payments] |
| Map type | [As-is / To-be / Both] |
| Version | [0.1] |
| Status | [Draft / Agreed / Superseded] |
| Owner | [@domain-architect] |
| Contributors | [@team-leads] |
| Related documents | [Bounded context canvases], [EventStorming summary], [ADRs] |
| Last updated | YYYY-MM-DD |

## 1. Scope and purpose

<!-- Guidance: What part of the organisation the map covers and which decision it supports (re-org, platform migration, new product, integration clean-up). A map without a question to answer becomes wall art. -->

[Scope statement. *Example:* This map covers the eight bounded contexts
involved from basket to doorstep. It supports the decision to replace the
legacy order management system and to split the Fulfilment team in two.]

## 2. Pattern reference

<!-- Guidance: Keep this table so readers who are new to DDD can interpret the map. The abbreviations are used in the diagram and the relationship register. -->

| Pattern | Abbrev. | Meaning in this map |
|---|---|---|
| Partnership | P | Two teams succeed or fail together and coordinate planning of shared features |
| Shared kernel | SK | Two contexts share a small, explicitly agreed part of the model and code; changes need both teams' consent |
| Customer-supplier | C/S | Upstream supplier plans with the downstream customer's needs in mind; the customer has a say in priorities |
| Conformist | CF | Downstream adopts the upstream model as is, because it has no influence over it |
| Anticorruption layer | ACL | Downstream translates the upstream model into its own, protecting its language |
| Open host service | OHS | Upstream offers a well-defined protocol or API that serves many consumers |
| Published language | PL | A documented, shared exchange format (schema, standard) used across the relationship |
| Separate ways | SW | No integration; each context solves its need independently |
| Big ball of mud | BBoM | A part of the system with mixed models and no clear boundary; contain it rather than spread it |

## 3. Bounded contexts

<!-- Guidance: One row per context in scope, including legacy systems and external vendors. Strategic classification helps decide where to invest. Link each context to its canvas. -->

| ID | Context | Classification | Owning team | Main responsibility | Canvas |
|---|---|---|---|---|---|
| BC-01 | *Example:* Catalogue | Supporting | Team Range | Products, prices shown to shoppers, availability flags | [Link] |
| BC-02 | *Example:* Basket and Checkout | Core | Team Checkout | Basket rules, substitutions preferences, order placement | [Link] |
| BC-03 | *Example:* Slot Booking | Core | Team Slots | Delivery slot offers and capacity | [Link] |
| BC-04 | *Example:* Fulfilment | Core | Team Fulfilment | Picking, substitution, van loading | [Link] |
| BC-05 | *Example:* Payments | Generic | Team Payments | Authorisation, capture, refunds via payment provider | [Link] |
| BC-06 | *Example:* Legacy OMS | Big ball of mud | Team Platform | Order state, invoices, customer service screens | n/a |
| BC-07 | *Example:* Payment provider | External | Vendor | Card processing | n/a |
| [BC-NN] | [Context] | [Core / Supporting / Generic / External] | [Team] | [Responsibility] | [Link] |

## 4. Context map diagram

<!-- Guidance: Upstream on the left or top, downstream on the right or bottom. Label each edge with U/D and the pattern abbreviations. Keep it to the contexts in section 3; draw a second diagram for the to-be state. -->

The diagram below shows the as-is relationships; arrows point from upstream
to downstream.

```mermaid
flowchart LR
  CAT["Catalogue"] -->|"U: OHS/PL  D: CF"| BAS["Basket and Checkout"]
  SLOT["Slot Booking"] <-->|"Partnership"| BAS
  BAS -->|"U: C/S  D"| FUL["Fulfilment"]
  OMS["Legacy OMS (BBoM)"] -->|"U  D: ACL"| FUL
  PROV["Payment provider"] -->|"U: OHS/PL  D: ACL"| PAY["Payments"]
  BAS -->|"U: C/S  D"| PAY
  FUL ---|"Shared kernel: Substitution rules"| BAS
```

## 5. Relationship register

<!-- Guidance: One row per edge in the diagram. State the pattern on each side, the integration mechanism and the main pain. Mistake: recording only the technology (REST, Kafka) without the model and team relationship. -->

| ID | Upstream | Downstream | Upstream pattern | Downstream pattern | Mechanism | Pain or risk |
|---|---|---|---|---|---|---|
| REL-01 | *Example:* Catalogue | Basket and Checkout | OHS + PL | Conformist | REST API, JSON schema `product.v2` | Price changes during checkout cause basket recalculation |
| REL-02 | *Example:* Slot Booking | Basket and Checkout | Partnership | Partnership | Events `SlotReserved`, `SlotReleased` | Joint releases needed for slot changes |
| REL-03 | *Example:* Basket and Checkout | Fulfilment | Supplier | Customer | Event `OrderPlaced` on message broker | Fulfilment needs fields that are not yet in the event |
| REL-04 | *Example:* Legacy OMS | Fulfilment | None (no influence) | ACL | Nightly database export, translated by adapter | Data is up to 24 hours stale |
| REL-05 | *Example:* Payment provider | Payments | OHS + PL | ACL | Provider SDK and webhooks | Provider model leaks into refund logic |
| REL-06 | *Example:* Fulfilment | Basket and Checkout | Shared kernel | Shared kernel | Shared library `substitution-rules` | Version drift between teams |
| [REL-NN] | [Context] | [Context] | [Pattern] | [Pattern] | [Mechanism] | [Pain] |

## 6. Team relationships

<!-- Guidance: Context relationships mirror team relationships. Record how the teams actually cooperate: shared planning, ticket requests, no contact. Conway's law means that a mismatch here predicts integration problems. -->

| Relationship | Teams | How they cooperate today | Healthy? | Action |
|---|---|---|---|---|
| REL-02 | *Example:* Team Slots and Team Checkout | Joint planning every two weeks, shared Slack channel | Yes | Keep |
| REL-03 | *Example:* Team Checkout and Team Fulfilment | Fulfilment raises tickets; prioritised quarterly | No | Move to monthly customer review of the `OrderPlaced` contract |
| REL-04 | *Example:* Team Platform and Team Fulfilment | No regular contact | No | Name an OMS contact; plan strangler migration |
| [REL-NN] | [Teams] | [Cooperation] | [Yes / No / Partly] | [Action] |

## 7. Integration details

<!-- Guidance: For each relationship that crosses a team boundary, link the contract and record ownership of the translation. Detailed API and event contracts belong in their own specifications. -->

| Relationship | Contract | Contract owner | Translation owner | Versioning | SLA / freshness |
|---|---|---|---|---|---|
| REL-01 | *Example:* `catalogue-api` OpenAPI | Team Range | None (conformist) | URI major version, 6-month deprecation | p95 120 ms, 99.9% |
| REL-03 | *Example:* `OrderPlaced` event schema v3 | Team Checkout | Team Fulfilment | Schema registry, backward compatible | Delivered within 5 s |
| REL-04 | *Example:* OMS export file | Team Platform | Team Fulfilment (ACL) | None | Daily at 02:00 |
| [REL-NN] | [Contract] | [Team] | [Team] | [Policy] | [SLA] |

## 8. Evolution plan

<!-- Guidance: The to-be map and the steps to get there. Each change should name the pattern change, the reason and the decision record. Typical moves: conformist to ACL when a model starts to hurt, big ball of mud to strangler with ACL, shared kernel to customer-supplier when teams drift apart. -->

The target map changes three relationships.

| ID | Change | From | To | Reason | Decision / ticket | Target date |
|---|---|---|---|---|---|---|
| EV-01 | *Example:* Replace OMS export with events | BBoM + ACL | OHS + PL from new Order context | Stale data causes missed substitutions | ADR-031 | YYYY-MM-DD |
| EV-02 | *Example:* Dissolve shared kernel for substitution rules | Shared kernel | Customer-supplier, Fulfilment upstream | Teams release on different cadences | ADR-034 | YYYY-MM-DD |
| EV-03 | *Example:* Add ACL in Basket for catalogue model | Conformist | ACL | Catalogue model change broke checkout twice | [Ticket] | YYYY-MM-DD |
| [EV-NN] | [Change] | [Pattern] | [Pattern] | [Reason] | [Link] | YYYY-MM-DD |

The to-be diagram shows the end state after EV-01 to EV-03.

```mermaid
flowchart LR
  CAT["Catalogue"] -->|"U: OHS/PL  D: ACL"| BAS["Basket and Checkout"]
  SLOT["Slot Booking"] <-->|"Partnership"| BAS
  BAS -->|"U: C/S  D"| ORD["Order (new)"]
  ORD -->|"U: OHS/PL  D"| FUL["Fulfilment"]
  FUL -->|"U: C/S  D"| BAS
  PROV["Payment provider"] -->|"U: OHS/PL  D: ACL"| PAY["Payments"]
```

## 9. Risks and open questions

<!-- Guidance: Record what could make the map wrong or the plan fail. -->

| ID | Risk or question | Owner | Mitigation or next step |
|---|---|---|---|
| R-01 | *Example:* New Order context needs OMS invoice logic that nobody fully understands | @platform-lead | EventStorming session on invoicing before EV-01 starts |
| R-02 | *Example:* Payments vendor change would require a new ACL | @payments-lead | Keep provider types out of the Payments domain model |
| [R-NN] | [Risk] | [@owner] | [Mitigation] |

## Standard and licence note

Based on the strategic design and context mapping patterns of
Domain-Driven Design (Eric Evans, *Domain-Driven Design*, 2003, and his
later *Domain-Driven Design Reference*, which adds the partnership
pattern). The pattern names are industry terms; all text,
tables and examples here are original to this collection. Template
licence: MIT.