---
id: MOD-CRM-REG
title: Regions
product_area: crm
module: regions
revision: 2
status: draft
source_sha:
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
repositories:
  - name: services-crm
    paths:
      - modules/regions
      - aws/crm.service.ts (RegionsPermissions)
      - tests/unit/regions-authorization.spec.ts
      - tests/e2e/dev/regions.dev.spec.ts
      - docs/migrations/crm-regions/README.md
      - docs/debt/region-custom-fields.md
      - 'modules/data-jobs/aws/api/bulk-data-jobs.routes.ts (region data-job routes, read for the boundary)'
      - 'modules/data-jobs/services/operations/configuration-imports.ts (region imports, read for the boundary)'
  - name: react-console
    paths:
      - components/regions
      - lib/configuration/regions.ts
      - lib/configuration/regions-analysis.ts
      - 'app/(console)/console/[tenantId]/configuration/[module]/[area]/assignmentRules'
      - components/configuration/area-route.tsx (the regions area)
      - lib/authz/backend-aliases.ts (regions keys)
      - e2e/dev/regions.dev.spec.ts
      - acceptance/crm/inventory (CAP-CRM-CFG-015 to 017)
      - acceptance/crm/journeys and acceptance/crm/playwright/journeys (regions journeys)
owns:
  - Regional definitions and their protection and integration fields
  - 'Workspace assignment policy, deciding address choices and ordered geographic coverage'
  - Recalculation records and their progress
  - Regional matching and coordination of placement updates owned by contact and organization persistence
  - Regional metadata registration and the region and policy export datasets
does_not_own:
  - record: 'Contact and organization records, address details, placement fields and record editors'
    owner: MOD-CRM-ENT
  - record: CRM address-purpose and other classification catalogues
    owner: MOD-CRM-ENT
  - record: Affiliation records and linked contact-detail resolution
    owner: MOD-CRM-ENT
  - record: Bulk import execution and job controls
    owner: MOD-PFM-DJE
  - record: 'Workspace lifecycle, reset and data export orchestration'
    owner: MOD-PFM-TNL
  - record: 'Security roles, permission evaluation and authority aliases'
    owner: MOD-PFM-SEC
  - record: 'Metadata infrastructure, generic record selectors and navigation'
    owner: MOD-PFM-MTD
  - record: 'Shared event capture, dispatch and queue processing'
    owner: Platform (macroservice libraries)
hosted_screens:
  - route: '/console/{tenantId}/configuration/crm/regions'
    purpose: 'Browse regional definitions or the saved policy, inspect recalculation and preview an address.'
  - route: '/console/{tenantId}/configuration/crm/regions/assignmentRules'
    purpose: Stage assignment choices and geographic coverage before saving the complete policy.
supersedes:
  - react-console acceptance inventory CAP-CRM-CFG-015
  - react-console acceptance inventory CAP-CRM-CFG-016
  - react-console acceptance inventory CAP-CRM-CFG-017
evidence:
  - >-
    services-crm: Examined regional routes, request schemas, declared tables, persistence, matching,
    reconciliation, recalculation, metadata and export at the pinned commit.
  - >-
    react-console: Examined regional components, configuration libraries, hosted routes, authorization aliases
    and regional test evidence at the pinned commit.
coverage_catalog: >-
  The examination report records the operation, table, permission, handler and test-file inventories with
  coverage and remaining gaps.
---

# Regions

## Purpose

Regions gives the customer a shared catalogue for its geographic groups and a policy for placing contacts and organizations within them. Staff maintain coverage, preserve deliberate exceptions and apply changed policy to existing records through recalculation. The planning layer distinguishes observed behavior from recorded product authority and remaining questions.

## Boundary

Regions owns its definitions, geographic policy and recalculation records. Contacts and organizations retain ownership of their record fields, address details, affiliations and editing surfaces; regional processing coordinates updates through that persistence. Platform and the shared service framework supply security, metadata, lifecycle orchestration and event delivery. The Data Job Engine owns imported-file processing behind the hosted regional routes.

## Features

| Feature | Name | Concepts | Capabilities | Journeys |
|---|---|---|---|---|
| `FEAT-CRM-REG-01` | Regional Catalogue | 1 | 5 | 1 |
| `FEAT-CRM-REG-02` | Geographic Assignment Policy | 1 | 5 | 1 |
| `FEAT-CRM-REG-03` | Record Placements | 1 | 2 | 2 |
| `FEAT-CRM-REG-04` | Policy Recalculation | 1 | 3 | 1 |

## Capabilities

| Capability | Feature | Outcome | Product Intent |
|---|---|---|---|
| `CAP-CRM-REG-001` | `FEAT-CRM-REG-01` | Maintain the region catalogue | proposed |
| `CAP-CRM-REG-002` | `FEAT-CRM-REG-01` | Retire regions while preserving their references | proposed |
| `CAP-CRM-REG-003` | `FEAT-CRM-REG-02` | Configure automatic placement and its address sources | proposed |
| `CAP-CRM-REG-004` | `FEAT-CRM-REG-02` | Build the geographic assignment policy | proposed |
| `CAP-CRM-REG-005` | `FEAT-CRM-REG-02` | Maintain individual rules alongside the shared policy | proposed |
| `CAP-CRM-REG-006` | `FEAT-CRM-REG-02` | Determine an address’s geographic region | proposed |
| `CAP-CRM-REG-007` | `FEAT-CRM-REG-02` | Check an address against the saved policy | proposed |
| `CAP-CRM-REG-008` | `FEAT-CRM-REG-03` | Keep placements aligned with address changes | proposed |
| `CAP-CRM-REG-009` | `FEAT-CRM-REG-03` | Preserve a deliberate regional exception | proposed |
| `CAP-CRM-REG-010` | `FEAT-CRM-REG-04` | Identify placements that need recalculation | proposed |
| `CAP-CRM-REG-011` | `FEAT-CRM-REG-04` | Apply the current policy across existing records | proposed |
| `CAP-CRM-REG-012` | `FEAT-CRM-REG-04` | Monitor recalculation and recover from failure | proposed |
| `CAP-CRM-REG-013` | `FEAT-CRM-REG-01` | Restrict regional work to authorised users | proposed |
| `CAP-CRM-REG-014` | `FEAT-CRM-REG-01` | Import a catalogue of regions | proposed |
| `CAP-CRM-REG-015` | `FEAT-CRM-REG-01` | Share regions through record references and exports | proposed |

## Journeys

| Journey | Outcome | Browser Policy |
|---|---|---|
| `JNY-CRM-REG-001` | An administrator establishes geographic placement | required |
| `JNY-CRM-REG-002` | An administrator applies revised coverage to existing records | required |
| `JNY-CRM-REG-003` | A coordinator maintains and releases a regional exception | required |
| `JNY-CRM-REG-004` | An administrator retires and removes a referenced region | optional |
| `JNY-CRM-REG-005` | An organization address change updates linked placements | optional |