Rhythm 2.0 Specifications

Appearance

DOM-CRM-REG-001Region

Markdown

DOM-CRM-REG-001

Region

Markdown
  • DocumentDraft
  • ImplementationObserved

Planning

Specified by
CON-CRM-REG-001

Design

Owned by
SVC-CRM-REG-regions

KindDomain objectProduct areaCRMModuleRegionsRevision2

Read atservices-crm a8d1364freact-console baf6dae3

Region ​

What It Models ​

A region gives staff a shared name for a chapter, territory or other grouping of people and organizations. Staff maintain these definitions in the regional catalogue. Geographic coverage belongs to the assignment policy; the definition supplies the target that records and rules reference.

Identity and Attributes ​

The workspace and permanent identifier identify a definition. Its name is required, and its description is optional. An active flag marks availability, while an external identifier supports integration. Customer locks can block deletion or all ordinary editing. The version advances on accepted updates, including unchanged updates. Regions declare no custom-field capability.

Relationships ​

Contacts, organizations and geographic rules hold references to the definition. The region does not own those records. References prevent deletion, and retirement preserves them. Older record references can survive the introduction of the regional constraints.

Invariants ​

The structured invariants identify the enforcing boundaries. Locks and optimistic version checks belong to regional persistence; naming and reference checks also have database enforcement. Retiring a target used by an enabled rule records a policy change, although matching continues to accept that target.

How It Is Stored and Shared ​

Regions owns the catalogue and supplies its record reads and writes. Metadata exposes the registered region as a reference target, exports include active and retired definitions, and imports call regional persistence. The workspace lifecycle participant removes regional data during reset or purge.

Open Design Questions ​

Product must settle inactive-target matching, complete-payload replacement and audited lock actions. Ordinary regional edits retain only the last modification stamp, so history and recovery of earlier values remain unresolved.

Relationships

ToCardinalityOwnershipCrosses a serviceOn archive or delete
DOM-CRM-REG-002A region can be targeted by any number of assignment rules.The policy holds the target reference, which prevents deleting its region.no
DOM-CRM-REG-003Any number of record placements can use one region.The record holds the placement reference, which prevents deleting its region.no
DOM-CRM-ENT-001Each contact has at most one regional reference; a region can serve many contacts.Entities owns the contact reference; new values must satisfy the workspace reference constraint.no
DOM-CRM-ENT-002Each organization has at most one regional reference; a region can serve many organizations.Entities owns the organization reference; new values must satisfy the workspace reference constraint.no

Invariants

InvariantProtectsEnforced atProvenance
INV-DOM-CRM-REG-001-01
Within a workspace, a regional identifier is unique and uses only the accepted legacy characters.
api, service, databaseobserved
services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table (integration) › constraints › keys a region by tenant and id: the same id in two tenants; services-crm:modules/regions/db/regions.table.ts:REGION_ID_PATTERN
INV-DOM-CRM-REG-001-02
A regional name must contain at least one non-space character.
api, databasetest
services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table (integration) › constraints › refuses a blank name
INV-DOM-CRM-REG-001-03
Deletion fails if a contact, organization or rule references the region, and the service reports the dependency category.
service, databaseobserved
services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table (integration) › references › refuses to delete a region an assignment rule names; services-crm:modules/regions/services/persistence/regions.ts:REGION_REFERENCES, regionRefusal
INV-DOM-CRM-REG-001-04
New references must resolve within the same workspace; older contact and organization references can remain unvalidated.
service, databaseobserved
services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table (integration) › references › refuses a contact naming a region its tenant does not have; services-crm:db/migrations/0019_regions.sql (contacts_region_fk and organizations_region_fk NOT VALID)
INV-DOM-CRM-REG-001-05
Full locks block region replacement and patching, and either lock kind blocks deletion.
serviceobserved
services-crm:modules/regions/services/persistence/regions.ts:updateRegionRow, deleteRegionRow
INV-DOM-CRM-REG-001-06
Replacement and patching must match the region’s current version.
api, servicetest
services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#the regions › answers 409 for a replace from a stale read
INV-DOM-CRM-REG-001-07
Retiring an enabled rule’s target increments the policy generation and stamps its change time in the regional save transaction.
serviceobserved
services-crm:modules/regions/services/persistence/regions.ts:updateRegion
INV-DOM-CRM-REG-001-08
Regional requests accept no custom-field values.
apiobserved
services-crm:docs/debt/region-custom-fields.md#Custom-field values of a region; services-crm:modules/regions/aws/api/regions.schemas.ts:regionRequestSchema; services-crm:modules/regions/metadata/regions.object.ts:regionsObject

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software