--- id: SVC-CRM-REG-regions title: Regions Service Module product_area: crm module: regions repository: services-crm source_module: modules/regions revision: 2 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-CRM-REG-001 - DOM-CRM-REG-002 - DOM-CRM-REG-003 - DOM-CRM-REG-004 does_not_own: - >- Entities retains ownership of contacts, organizations, addresses, affiliations and their editing surfaces; regional placement uses its persistence functions. - 'The selected address types belong to Entities, with restricting references held by regional policy.' - >- The Data Job Engine owns file processing, job state and controls for the twelve regional hosted operations. - 'Platform supplies authorization, metadata infrastructure, workspace export and lifecycle orchestration.' - 'Shared macroservice libraries manage captured events, dispatch, queue retry and dead-letter delivery.' operations: - operation_id: getRegionsHealth intent: Check whether the regional function responds and identify its deployed build. access: public permission: 'none: public health route' realises: [] published_to_submissions: 'not published: infrastructure health does not collect product data.' provenance: observed source: >- services-crm:modules/regions/aws/api/regions.routes.ts:regionsModuleRoutes (healthRoute); services-crm:package-lock.json#@rhythmsoftware/macroservice-http 0.18.0 (integrity-verified package dist/health-route.js:healthRoute) - operation_id: createRegion intent: Create a named catalogue region using a caller-supplied or generated identity. access: console permission: crm.regions.create realises: - CAP-CRM-REG-001 - CAP-CRM-REG-013 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:createRegion' - operation_id: listRegions intent: Browse the local catalogue in paged bytewise identifier order. access: console permission: crm.regions.read realises: - CAP-CRM-REG-001 - CAP-CRM-REG-015 published_to_submissions: 'not published: this read inspects existing records and accepts no captured submission.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:listRegions' - operation_id: getRegion intent: Retrieve the selected workspace region. access: console permission: crm.regions.read realises: - CAP-CRM-REG-001 - CAP-CRM-REG-015 published_to_submissions: 'not published: this read inspects existing records and accepts no captured submission.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegion' - operation_id: updateRegion intent: 'Save a replacement definition at the supplied current version, including its availability.' access: console permission: crm.regions.update realises: - CAP-CRM-REG-001 - CAP-CRM-REG-002 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:updateRegion' - operation_id: patchRegion intent: Apply version-tested changes to an existing definition. access: console permission: crm.regions.update realises: - CAP-CRM-REG-001 - CAP-CRM-REG-002 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:patchRegion' - operation_id: deleteRegion intent: Delete a definition only after its locks and dependencies permit removal. access: console permission: crm.regions.delete realises: - CAP-CRM-REG-002 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:deleteRegion' - operation_id: getRegionAssignmentSettings intent: 'Inspect saved assignment choices, ordered rules and the outstanding-recalculation flag.' access: console permission: crm.regions.read realises: - CAP-CRM-REG-003 - CAP-CRM-REG-004 - CAP-CRM-REG-010 published_to_submissions: 'not published: this read inspects existing records and accepts no captured submission.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegionAssignmentSettings' - operation_id: updateRegionAssignmentSettings intent: Save assignment choices and optionally replace all coverage without updating placements. access: console permission: crm.regions.update realises: - CAP-CRM-REG-003 - CAP-CRM-REG-004 - CAP-CRM-REG-010 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:updateRegionAssignmentSettings' - operation_id: listRegionAssignmentRules intent: Retrieve the ordered regional coverage rules within the configured limit. access: console permission: crm.regions.read realises: - CAP-CRM-REG-005 - CAP-CRM-REG-004 published_to_submissions: 'not published: this read inspects existing records and accepts no captured submission.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:listRegionAssignmentRules' - operation_id: createRegionAssignmentRule intent: Insert a geographic rule at the requested position or append it. access: console permission: crm.regions.update realises: - CAP-CRM-REG-005 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:createRegionAssignmentRule' - operation_id: reorderRegionAssignmentRules intent: Replace evaluation order with a complete list containing each existing rule once. access: console permission: crm.regions.update realises: - CAP-CRM-REG-005 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:reorderRegionAssignmentRules' - operation_id: previewRegionAssignment intent: Evaluate an address against saved coverage and return its match without persistence. access: console permission: crm.regions.read realises: - CAP-CRM-REG-007 - CAP-CRM-REG-006 published_to_submissions: 'not published: saved-policy preview produces an answer without capturing a record.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:previewRegionAssignment' - operation_id: getRegionAssignmentRule intent: Retrieve a selected regional coverage rule. access: console permission: crm.regions.read realises: - CAP-CRM-REG-005 published_to_submissions: 'not published: this read inspects existing records and accepts no captured submission.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegionAssignmentRule' - operation_id: updateRegionAssignmentRule intent: Save a versioned replacement of one rule without changing its position. access: console permission: crm.regions.update realises: - CAP-CRM-REG-005 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:updateRegionAssignmentRule' - operation_id: patchRegionAssignmentRule intent: Change one rule through a version-tested patch. access: console permission: crm.regions.update realises: - CAP-CRM-REG-005 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:patchRegionAssignmentRule' - operation_id: deleteRegionAssignmentRule intent: Remove a coverage rule and close the remaining position gap. access: console permission: crm.regions.update realises: - CAP-CRM-REG-005 published_to_submissions: 'not published: authorized staff maintain workspace configuration through this operation.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:deleteRegionAssignmentRule' - operation_id: recalculateRegionAssignments intent: Create or select a running recalculation and execute its request-budget batches. access: console permission: crm.regions.recalculate realises: - CAP-CRM-REG-011 published_to_submissions: 'not published: workspace maintenance requires recalculation authority rather than intake access.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:recalculateRegionAssignments' - operation_id: listRegionRecalculations intent: Inspect recent local recalculations in newest-first order. access: console permission: crm.regions.read realises: - CAP-CRM-REG-012 published_to_submissions: 'not published: this read inspects existing records and accepts no captured submission.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:listRegionRecalculations' - operation_id: getRegionRecalculation intent: 'Inspect one run’s traversal outcome, counts and retained error.' access: console permission: crm.regions.read realises: - CAP-CRM-REG-012 published_to_submissions: 'not published: this read inspects existing records and accepts no captured submission.' provenance: observed source: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegionRecalculation' - operation_id: submitRegionsDataJob intent: Accept an uploaded regional file for delegated import processing. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: listRegionsDataJobs intent: Browse regional import executions for the workspace. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: getRegionsDataJob intent: Inspect a selected regional import execution. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: readRegionsBySourceKey intent: Resolve up to 100 producer keys to their resulting regional records. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: listRegionsDataJobResults intent: Inspect item outcomes for a regional import. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: listRegionsDataJobRejections intent: Inspect rejected items from a regional import. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: applyRegionsDataJob intent: Authorize application of the validated regional import. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: pauseRegionsDataJob intent: Pause new import batches while in-flight work may finish. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: resumeRegionsDataJob intent: Release paused regional work for further processing. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: cancelRegionsDataJob intent: Cancel further regional import work while preserving committed changes. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: retryRegionsDataJob intent: Request another attempt for eligible paused import work. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS - operation_id: revalidateRegionsDataJobConflicts intent: Create another validation of records skipped for conflicts by a finished regional job. access: console permission: crm.regions.bulk and crm.regions.update (both required) realises: - CAP-CRM-REG-014 published_to_submissions: 'not published: delegated bulk-job management is outside submission capture.' provenance: observed source: >- services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes, BULK_SUBMISSIONS events: - name: contact change event (stream contact) direction: consumed when: A contact change includes addresses or an update changes its override. payload_summary: Record identity and changed fields select processing; current record input is read separately. - name: organization change event (stream organization) direction: consumed when: An organization change includes addresses or an update changes its override. payload_summary: Record identity and related address identifiers support both organization and linked-contact processing. - name: contact and organization change events from placement writes direction: produced when: Entities capture observes a changed regional reference or fingerprint from placement persistence. payload_summary: 'Changed regional fields carry no address edit, preventing an address-assignment loop.' - name: region recalculation change event (stream region_recalculation) direction: produced when: 'Insertion creates a run, or continuation requests more worker time.' payload_summary: >- Run identity and workspace select the persisted execution; batch progress alone does not request another worker. - name: region recalculation change event (stream region_recalculation) direction: consumed when: The registered runner receives the run’s initial or continuation message. payload_summary: The run identifier selects the committed status and cursor to resume. jobs: - >- The recalculation runner executes forty-second worker budgets and uses captured continuation updates to request more work. - >- Address and override handlers reconcile the corresponding contact or organization from current record input. - The linked-contact handler processes collected contact identifiers in groups of 500. - Bulk regional import execution belongs to the engine invoked by hosted submission routes. integrations: - system: Platform metadata direction: outbound contract: The Region registration supplies the reference target and regional display fields for CRM records. - system: Platform workspace data export direction: outbound contract: >- Catalogue and saved-policy datasets expose regional configuration; policy export declares region and address-type prerequisites. - system: Platform workspace lifecycle direction: outbound contract: >- The regional lifecycle participant seeds no regional defaults, removes dependent regional data in order, and coordinates reseeding of baseline detail types during reset. consistency: - rule: >- A region update and any enabled-target retirement stamp commit in the same transaction after locking the definition. kind: transactional compensation: Rollback removes the failed regional update and stamp. - rule: A settings save validates before persisting settings and any supplied full rule list in one transaction. kind: transactional compensation: Rollback preserves the previously stored settings and coverage. - rule: >- Individual rule changes commit with generation and settings-version updates under an existing policy-row lock. kind: transactional compensation: Rollback leaves no partial rule update or counter advance. - rule: >- Record placement is reconciled after address commit under record locks; equal fingerprints suppress repeats, but policy reads can interleave with policy saves. kind: eventual compensation: >- Reconciliation rollback preserves the previous facet; the queue retries, and exhausted messages require redrive or a later applicable trigger. - rule: Linked-contact placement advances through independently committed reconciliation batches. kind: eventual compensation: Committed contact batches remain; redelivery reevaluates input and avoids equal-fingerprint writes. - rule: >- Each recalculation batch commits placement writes and traversal progress atomically while the overall run advances incrementally. kind: eventual compensation: >- Earlier committed batches remain. A failed run requires another start, while failed terminal settlement can require manual recovery. - rule: 'Policy saves do not directly update placements, and reads derive outstanding work from generations.' kind: transactional compensation: No placement compensation is applicable to the policy write. evidence: - >- services-crm at a8d1364f: modules/regions/aws/api/regions.routes.ts (regionsRoutes, regionsModuleRoutes); aws/regions.module.ts; aws/logic/regions-api.lambda.ts; aws/lambda/API.handler.ts; modules/data-jobs/aws/api/bulk-data-jobs.routes.ts (configurationDataJobRoutes, regionDataJobsRoutes); modules/data-jobs/aws/api/records-by-source-key.routes.ts; aws/crm.service.ts (RegionsPermissions); aws/crm.change-events.ts; modules/regions/metadata, export; modules/tenant-lifecycle/services/participants/regions-participant.ts (read for the boundary). - >- services-crm:package-lock.json pins @rhythmsoftware/macroservice-http 0.18.0; the integrity-verified healthRoute factory declares getRegionsHealth with public access. - >- services-crm:modules/regions/services/persistence/region-assignment-settings.ts:readRegionAssignmentSettings; services-crm:modules/data-jobs/services/operations/configuration-import.ts:expectedVersionOf controls: [TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-IAM-001, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003] --- # Regions Service Module ## What This Service Is For Regions maintains the geographic catalogue and coverage used to place people and organizations. It supplies saved-policy preview, recalculation and reactions to committed address changes. Staff can also choose regions through Entities record editing. ## Boundary Regions owns definitions, policy, runs and automatic placement decisions. Entities stores the placement facet and provides the persistence functions used in regional processing. The hosted import routes delegate execution to the Data Job Engine. Platform supplies shared security, metadata, export and lifecycle infrastructure. ## Operations in Words Catalogue operations create, inspect, edit and remove definitions. Updates use versions; deletion uses locks and reference checks. Policy operations support a full settings-and-rules save or individual-rule maintenance and complete reorder. Preview evaluates saved coverage without changing records. Recalculation has an authorized start and workspace-scoped history reads. Twelve hosted import operations support file acceptance, review, application and controls, all requiring both regional bulk and update keys. Health is public; other declared operations require console access. No scoped operation publishes a Submissions binding. ## Events and Jobs Contact and organization address or override changes invoke reconciliation. Organization address changes also invoke linked-contact processing. Regional writes do not change addresses and cannot trigger another address reaction. Recalculation uses initial and continuation events on its own stream. No scoped regional caller makes a model request. ## Consistency Guarantees Local persistence transactions prevent partial definition, policy and batch writes. Event processing and linked-contact batches provide delayed placement updates. Recalculation retains completed batches rather than compensating them. Policy initialization, unlocked policy reads and best-effort terminal failure settlement qualify stronger concurrency and recovery promises.