{
    "slug": "context_mapping",
    "term": "Context Mapping",
    "category": "architecture",
    "difficulty": "advanced",
    "short": "A DDD strategic pattern that maps the relationships between bounded contexts — defining integration patterns like Anti-Corruption Layer, Shared Kernel, and Customer-Supplier.",
    "long": "Context mapping identifies how different bounded contexts relate to each other: which is upstream (produces) and downstream (consumes), and what integration pattern is appropriate. Patterns: Partnership (collaborate closely), Shared Kernel (shared model subset), Customer-Supplier (upstream provides, downstream requests), Conformist (downstream adopts upstream model), ACL (downstream translates), Open Host (upstream publishes a protocol), Published Language (formal exchange format). The context map is a team topology tool as much as a technical one.",
    "aliases": [
        "bounded context integration",
        "DDD context map",
        "upstream downstream"
    ],
    "tags": [
        "architecture",
        "ddd",
        "strategic-design"
    ],
    "misconception": "Context mapping is just API design — it defines the organisational relationships and power dynamics between teams, which determines what integration pattern is even feasible.",
    "why_it_matters": "Context maps prevent integration anti-patterns — a Conformist relationship between two teams where the downstream should have an ACL produces an unmaintainable codebase when the upstream changes.",
    "common_mistakes": [
        "Not mapping all contexts — undocumented integrations are the ones that produce the worst coupling.",
        "Choosing Shared Kernel for convenience — it requires joint ownership and coordination; it is often the wrong choice.",
        "Conformist when ACL is needed — absorbing an upstream model directly pollutes the downstream domain.",
        "Not updating the context map when team structures change — Conway's Law means team changes affect integration patterns."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "bounded_context",
        "anti_corruption_layer",
        "domain_driven_design",
        "event_storming"
    ],
    "prerequisites": [
        "bounded_context",
        "domain_driven_design",
        "anti_corruption_layer"
    ],
    "refs": [
        "https://martinfowler.com/bliki/BoundedContext.html"
    ],
    "bad_code": "// Conformist — downstream absorbs upstream model uncritically:\n// Legacy CRM uses 'CUSTNO', 'ACCT_STATUS_CD', 'AMT_OUTSTANDING'\n\nclass InvoiceService {\n    public function generateInvoice(string $custNo, string $acctStatusCd): Invoice {\n        // Upstream's naming convention pollutes the entire downstream domain\n        // Every developer must know what ACCT_STATUS_CD means\n    }\n}",
    "good_code": "// ACL pattern — downstream translates upstream model:\nclass CrmTranslator {  // Anti-Corruption Layer\n    public function toCustomer(array $crmData): Customer {\n        return new Customer(\n            id: new CustomerId($crmData['CUSTNO']),\n            status: match($crmData['ACCT_STATUS_CD']) {\n                'A' => CustomerStatus::Active,\n                'S' => CustomerStatus::Suspended,\n            },\n            balance: Money::fromCents((int)($crmData['AMT_OUTSTANDING'] * 100), 'GBP'),\n        );\n    }\n}",
    "quick_fix": "Draw a context map with your team — identify which bounded contexts you own, which are external, and what relationship pattern exists between each pair (conformist, ACL, partnership)",
    "severity": "info",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/context_mapping",
        "html_url": "https://codeclaritylab.com/glossary/context_mapping",
        "json_url": "https://codeclaritylab.com/glossary/context_mapping.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Context Mapping](https://codeclaritylab.com/glossary/context_mapping) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/context_mapping"
            }
        }
    }
}