--- id: RESP-CRM title: CRM Responsibilities product_area: crm revision: 4 status: draft design_intent: proposed source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f modules: - module: MOD-CRM-ENT owns: - DOM-CRM-ENT-001 - DOM-CRM-ENT-002 - DOM-CRM-ENT-003 - DOM-CRM-ENT-033 exposes: operations: - getEntitiesHealth - createContact - listContacts - recursivelyListContactsForOrganizationId - getContact - getContactMailingAddress - updateContact - patchContact - deleteContact - reconcileAffiliationDates - archiveContact - unarchiveContact - verifyContactAddress - relinkContactAddress - removeContactAddress - verifyContactPhoneNumber - relinkContactPhoneNumber - removeContactPhoneNumber - listContactHistory - listContactHistoryActors - getContactRevision - listMergedContactHistory - listMergedContactHistoryActors - getMergedContactRevision - lockContact - unlockContact - listContactLockChanges - createOrganization - listOrganizations - getOrganization - listOrganizationAffiliations - updateOrganization - patchOrganization - reprocessCompliance - previewContactRoleComplianceEmail - archiveOrganization - unarchiveOrganization - deleteOrganization - listOrganizationHistory - listOrganizationHistoryActors - getOrganizationRevision - lockOrganization - unlockOrganization - listOrganizationLockChanges - getCrmSettings - patchCrmSettings - getEffectiveDefinitions - renderEmailPreview - getConfigurationTypesHealth - createOrganizationType - listOrganizationTypes - reorderOrganizationTypes - getOrganizationType - updateOrganizationType - patchOrganizationType - deleteOrganizationType - createContactRole - listContactRoles - reorderContactRoles - getContactRole - updateContactRole - patchContactRole - lockContactRole - unlockContactRole - listContactRoleLockChanges - deleteContactRole - createContactType - listContactTypes - reorderContactTypes - getContactType - updateContactType - patchContactType - deleteContactType - createAffiliationType - listAffiliationTypes - getAffiliationType - updateAffiliationType - patchAffiliationType - deleteAffiliationType - createAddressType - listAddressTypes - reorderAddressTypes - getAddressType - updateAddressType - patchAddressType - deleteAddressType - createPhoneNumberType - listPhoneNumberTypes - reorderPhoneNumberTypes - getPhoneNumberType - updatePhoneNumberType - patchPhoneNumberType - deletePhoneNumberType events: - contact change event (stream contact) - organization change event (stream organization) - compliance reprocess change event (stream compliance_reprocess) - crm.organizations_out_of_compliance attention item (behind the attention publishing switch) delegates: - concern: >- Custom definitions, presentation definitions and associated custom records with their owner-deletion policy to: MOD-PFM-MTD - concern: 'Identity, roles, permission decisions, application access and signed authorization context' to: MOD-PFM-SEC - concern: 'Contact and organization search indexes, dataset exploration and result export' to: MOD-PFM-QRY - concern: 'Owned communication templates, rendering, message delivery and communication outcomes' to: MOD-PFM-NOT - concern: Attention publication and responsibility assignment to: MOD-PFM-ELG - concern: 'Job and data-job engines, file lifecycle, number allocation and shared history presentation' to: MOD-PFM-OPS - concern: 'Workspace lifecycle, initial data and purge that ends revision retention' to: MOD-PFM-TNL - concern: 'Duplicate configuration, creation blocking, merge persistence and merged-identity forwarding' to: MOD-CRM-DQ - concern: Region definitions and automatic assignment from deciding addresses to: MOD-CRM-REG - concern: 'Bulk changes and imports for people, organizations and classification catalogues' to: MOD-CRM-DJB - concern: Activities and tasks referencing CRM records to: MOD-CRM-ACT - concern: 'Future person or organization capture bindings, which the scoped implementation has not published' to: Submissions product area guarantees: - INV-DOM-CRM-ENT-001-01 - INV-DOM-CRM-ENT-001-03 - INV-DOM-CRM-ENT-001-05 - INV-DOM-CRM-ENT-001-09 - INV-DOM-CRM-ENT-001-10 - INV-DOM-CRM-ENT-001-11 - INV-DOM-CRM-ENT-002-04 - INV-DOM-CRM-ENT-002-06 - INV-DOM-CRM-ENT-002-08 - INV-DOM-CRM-ENT-002-10 - INV-DOM-CRM-ENT-003-02 - INV-DOM-CRM-ENT-003-03 - INV-DOM-CRM-ENT-003-07 - INV-DOM-CRM-ENT-003-10 - INV-DOM-CRM-ENT-003-11 - INV-DOM-CRM-ENT-033-01 - INV-DOM-CRM-ENT-033-02 - INV-DOM-CRM-ENT-033-03 - INV-DOM-CRM-ENT-033-04 - INV-DOM-CRM-ENT-033-07 - INV-DOM-CRM-ENT-033-08 - INV-DOM-CRM-ENT-033-09 - module: MOD-CRM-DQ owns: - DOM-CRM-DQ-001 - DOM-CRM-DQ-003 - DOM-CRM-DQ-004 exposes: operations: - getDuplicatesHealth - listDuplicateGroups - getDuplicateGroup - dismissDuplicateGroup - restoreDuplicateGroupDismissal - getDuplicateSummary - listDuplicateCandidates - addManualDuplicateCandidate - getDuplicateCandidate - listRecordDuplicateCandidates - dismissDuplicateCandidate - restoreDuplicateCandidate - checkForDuplicates - startDuplicateRescan - listDuplicateRescans - getDuplicateRescan - listDuplicateRules - updateDuplicateRule - getMergesHealth - createMergePlan - listMergePlans - getMergeLimits - getMergePlan - updateMergePlan - validateMergePlan - executeMergePlan - listRecordMerges - getRecordMerge - getRecordMergeDetails - listMergesIntoRecord - getMergeIntoRecord - getMergedRecordAlias events: - Committed contact-merge business event - Merge audit pointer on each participating record - 'Declared duplicate-group attention, held pending metadata registration' - Contact and organization change streams handled by duplicate detection delegates: - concern: >- Ordinary contact and organization creation, survivor saving, participant deletion, record routes and history to: MOD-CRM-ENT - concern: 'Change dispatch, durable execution, job monitoring and reconciliation' to: MOD-PFM-OPS - concern: 'Portal identity, sign-up linking, merge-time login transfer and security audit' to: MOD-PFM-SEC - concern: Publication of attention and assignment of responsibility to: MOD-PFM-ELG - concern: 'Workspace provisioning, export, reset and purge coordination' to: MOD-PFM-TNL - concern: Search and saved views that follow absorbed identities to: MOD-PFM-QRY - concern: Activity and task references updated under CRM reference policies to: MOD-CRM-ACT - concern: Region updates driven by committed record changes to: MOD-CRM-REG - concern: Application-owned participant functions for references outside CRM to: Their owning modules guarantees: - INV-DOM-CRM-DQ-001-04 - INV-DOM-CRM-DQ-001-05 - INV-DOM-CRM-DQ-001-07 - INV-DOM-CRM-DQ-001-09 - INV-DOM-CRM-DQ-001-10 - INV-DOM-CRM-DQ-001-12 - INV-DOM-CRM-DQ-003-07 - INV-DOM-CRM-DQ-003-09 - INV-DOM-CRM-DQ-004-01 - INV-DOM-CRM-DQ-004-04 - INV-DOM-CRM-DQ-004-05 - INV-DOM-CRM-DQ-004-06 - INV-DOM-CRM-DQ-004-08 - INV-DOM-CRM-DQ-004-10 - module: MOD-CRM-REG owns: - DOM-CRM-REG-001 - DOM-CRM-REG-002 - DOM-CRM-REG-003 - DOM-CRM-REG-004 exposes: operations: - getRegionsHealth - createRegion - listRegions - getRegion - updateRegion - patchRegion - deleteRegion - getRegionAssignmentSettings - updateRegionAssignmentSettings - listRegionAssignmentRules - createRegionAssignmentRule - reorderRegionAssignmentRules - previewRegionAssignment - getRegionAssignmentRule - updateRegionAssignmentRule - patchRegionAssignmentRule - deleteRegionAssignmentRule - recalculateRegionAssignments - listRegionRecalculations - getRegionRecalculation - submitRegionsDataJob - listRegionsDataJobs - getRegionsDataJob - readRegionsBySourceKey - listRegionsDataJobResults - listRegionsDataJobRejections - applyRegionsDataJob - pauseRegionsDataJob - resumeRegionsDataJob - cancelRegionsDataJob - retryRegionsDataJob - revalidateRegionsDataJobConflicts events: - Captured recalculation insertion and continuation on the regional run stream - Placement changes captured by Entities on contact and organization streams without address updates delegates: - concern: >- Contact and organization placement storage, deciding-address resolution, linked details and record editing to: MOD-CRM-ENT - concern: The address-type catalogue selected by regional policy to: MOD-CRM-ENT - concern: Evaluation of regional authority in the verified security context to: MOD-PFM-SEC - concern: Metadata infrastructure exposing the registered Region reference target to: MOD-PFM-MTD - concern: Workspace export orchestration for regional catalogue and saved-policy datasets to: MOD-PFM-QRY - concern: 'File-import validation, execution, outcomes and job controls' to: MOD-PFM-DJE - concern: Workspace lifecycle coordination for regional reset and purge to: MOD-PFM-TNL - concern: 'Captured-change publication, delivery attempts and dead-letter processing' to: Platform (macroservice libraries) - concern: Shared history and audited-lock facilities that regional definitions have not yet adopted to: MOD-PFM-OPS guarantees: - INV-DOM-CRM-REG-001-03 - INV-DOM-CRM-REG-001-04 - INV-DOM-CRM-REG-001-06 - INV-DOM-CRM-REG-001-07 - INV-DOM-CRM-REG-002-01 - INV-DOM-CRM-REG-002-03 - INV-DOM-CRM-REG-002-07 - INV-DOM-CRM-REG-002-08 - INV-DOM-CRM-REG-002-09 - INV-DOM-CRM-REG-003-01 - INV-DOM-CRM-REG-003-02 - INV-DOM-CRM-REG-003-04 - INV-DOM-CRM-REG-003-05 - INV-DOM-CRM-REG-004-01 - INV-DOM-CRM-REG-004-04 - INV-DOM-CRM-REG-004-05 - INV-DOM-CRM-REG-004-06 - module: MOD-CRM-ACT owns: - DOM-CRM-ACT-001 - DOM-CRM-ACT-003 - DOM-CRM-ACT-005 exposes: operations: - getActivitiesHealth - createActivity - getActivity - updateActivity - patchActivity - deleteActivity - listActivityHistory - getActivityRevision - listActivityHistoryActors - createActivityType - listActivityTypes - reorderActivityTypes - getActivityType - updateActivityType - deleteActivityType - getContactTimeline - getOrganizationTimeline - getContactTimelineSummary - getOrganizationTimelineSummary - getTasksHealth - createTask - getTask - updateTask - patchTask - deleteTask - assignTask - claimTask - releaseTask - completeTask - reopenTask - cancelTask - listOfferedTasks - runTaskServiceOperation - createTaskType - getTaskType - updateTaskType - patchTaskType - deleteTaskType - createTaskQueue - getTaskQueue - updateTaskQueue - patchTaskQueue - deleteTaskQueue - listTaskTypes - reorderTaskTypes - listTaskQueues - reorderTaskQueues events: - 'activity change event (stream activity, history only)' - >- crm.tasks_overdue attention item (behind the attention publishing switch) delegates: - concern: >- User and role authority, permission evaluation and the current role-holder answer used for role-only claims. to: MOD-PFM-SEC - concern: >- Execution of registered workspace interaction and task queries, counts, saved views and exports. to: MOD-PFM-QRY - concern: >- Overdue item delivery, Home discovery and assignment of shared-work responsibility. to: MOD-PFM-ELG - concern: >- Workflow execution and the external task-action adapters that invoke CRM. to: MOD-PFM-INT - concern: >- Shared supporting-file preparation, storage and physical cleanup after release. to: MOD-PFM-MTD - concern: >- Workspace lifecycle orchestration and external participant registration. to: MOD-PFM-TNL - concern: >- Bulk interaction and category processing and import execution on the data job engine. to: MOD-PFM-DJE - concern: >- Duplicate-record preview and execution with association and task-context transfer. to: MOD-CRM-DQ - concern: >- Contact and organization persistence and the record screens that host timelines. to: MOD-CRM-ENT - concern: >- Revision storage supplied through the shared CRM record-history implementation. to: MOD-CRM-ENT - concern: Shared revision presentation and audit infrastructure. to: MOD-PFM-OPS guarantees: - INV-DOM-CRM-ACT-001-01 - INV-DOM-CRM-ACT-001-02 - INV-DOM-CRM-ACT-001-03 - INV-DOM-CRM-ACT-001-06 - INV-DOM-CRM-ACT-001-07 - INV-DOM-CRM-ACT-001-08 - INV-DOM-CRM-ACT-001-10 - INV-DOM-CRM-ACT-001-12 - INV-DOM-CRM-ACT-001-14 - INV-DOM-CRM-ACT-003-02 - INV-DOM-CRM-ACT-003-03 - INV-DOM-CRM-ACT-003-05 - INV-DOM-CRM-ACT-003-06 - INV-DOM-CRM-ACT-003-07 - INV-DOM-CRM-ACT-003-09 - INV-DOM-CRM-ACT-003-10 - INV-DOM-CRM-ACT-003-11 - INV-DOM-CRM-ACT-005-01 - INV-DOM-CRM-ACT-005-02 - INV-DOM-CRM-ACT-005-03 source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f evidence: - >- services-crm at 7ea48a41: modules/entities/**; modules/configuration-types/**; aws/crm.change-events.ts; aws/crm.service.ts; docs/change-events.md. - >- services-platform at ad3f6a65: docs/standards/**; docs/queued-work.md; docs/jobs.md; docs/record-history.md; docs/row-level-security.md. - >- rhythm-v2-docs: specs/PRODUCT-AREAS.md (CRM modules); specs/crm/entities/design/contracts/*; specs/crm/data-quality/design/contracts/*. - >- services-crm at a8d1364f (Data Quality section): modules/duplicates/**; modules/merges/**; aws/lambda/JOB_RECONCILER.ts; db/migrations/0077_portal_sign_up_contacts.sql; modules/tenant-lifecycle/services/participants/{duplicates,merges}-participant.ts. - >- services-crm at a8d1364f (the Regions row): modules/regions/**; modules/data-jobs/aws/api/bulk-data-jobs.routes.ts (region routes); modules/entities/services/persistence/contacts.ts and organizations.ts (region functions); aws/crm.change-events.ts. - 'rhythm-v2-docs: specs/crm/regions/design/contracts/SVC-CRM-REG-regions.md.' - >- services-crm at 7ea48a41: modules/entities/**; modules/configuration-types/**; aws/crm.change-events.ts; aws/crm.service.ts; docs/change-events.md. - >- services-platform at ad3f6a65: docs/standards/**; docs/queued-work.md; docs/jobs.md; docs/record-history.md; docs/row-level-security.md. - >- rhythm-v2-docs: specs/PRODUCT-AREAS.md (CRM modules); specs/crm/entities/design/contracts/*; specs/crm/data-quality/design/contracts/*. - >- services-crm at a8d1364f (Data Quality section): modules/duplicates/**; modules/merges/**; aws/lambda/JOB_RECONCILER.ts; db/migrations/0077_portal_sign_up_contacts.sql; modules/tenant-lifecycle/services/participants/{duplicates,merges}-participant.ts. - >- services-crm at a8d1364f and react-console at baf6dae3 (Activities and Tasks section): modules/activities/**, modules/tasks/**, aws/crm.service-functions.ts, aws/crm.attention.ts, aws/crm.attention-sweeps.ts, aws/crm.responsibilities.ts; rhythm-v2-docs specs/crm/activities-tasks/design/contracts/*. --- # CRM Responsibilities ## How the Product Area Is Divided CRM keeps the customer's people and organizations and the work done around them. Entities is the core: it owns the people, the organizations, the ties between them and the safeguards that protect and explain every change. Around it, other CRM modules each own one concern and work through Entities' records or react to their changes: data quality finds and merges duplicates, regions assign people and organizations to geographic or organizational regions, data jobs run bulk updates and imports, and activities and tasks record the work staff do with people. Entities, Data Quality and Regions are designed so far; the others are named here so the boundary is clear, and each gets its own section when its design is drafted. ## Entities Entities is the record owner for contacts, organizations and contact-owned affiliations and role periods. Its safeguard model covers versions, customer locking, independent Rhythm protection, archive metadata, contact and organization revisions, and workspace CRM defaults. Classification catalogues remain within this ownership even though a separate function hosts their routes. The module exposes record creation, reading, editing and removal, dedicated archive and customer-lock actions, history reads, disconnected-detail resolution, date settlement, compliance scans and notice preview. It also exposes permission-filtered presentation defaults and classification maintenance. The structured operation list is the boundary inventory. Changed contact and organization transactions capture aggregate revisions and events. Independent handlers perform compliance and projections after commit. Accepted notice pointers commit with the compliance transition and deduplicate recipient batches; Platform owns delivery outcomes. The guarantee references point to the object invariants and their enforcement evidence. Implementation qualifications distinguish that boundary: deletion is unversioned, classification records lack record history, unchanged type writes can advance versions, and legacy contact-role saves can bypass lock audit. Complete replacement, stale no-op handling, explicit relationship operations and deployment activation still need implementation or product resolution. ## Data Quality Data Quality identifies possible duplicate people and organizations and supports an authorized decision to combine them. Its duplicate service owns matching keys, candidate pairs, review groups, workspace rules, creation exceptions and rechecks. Its merge service owns plans, attempts, durable-job links and forwarding aliases. Detection runs after committed record changes. Pair decisions rebuild affected groups in their transaction, while replacing matching keys and writing new pairs can use separate transactions. Creation blocking applies to ordinary creation; an authorized exception is recorded alongside the admitted record. Merge execution encloses participating database changes in one transaction. A rolled-back running claim remains queued until separate failure settlement; a caught execution error normally produces a failed attempt rather than an automatic business retry. The originals remain in merge outcomes, and forwarding aliases preserve absorbed identities, although deleting a survivor can leave their destination absent. Ordinary survivor saves and participant deletion call Entities. Merge-owned persistence also rewrites references, moves affiliations and prepares organization parentage, while other applications supply their own participant functions. The module declares no custom-field support and publishes no operations to Submissions. ## Regions Regions owns the catalogue, geographic policy, recalculation runs and automatic placement decisions. Entities owns the contacts and organizations that store regional values and permits authorized staff selections. Regional processing reads and writes the record’s placement facet through Entities persistence rather than storing another copy. The regional surface provides catalogue maintenance, complete-policy saving, individual-rule operations, saved-policy preview and recalculation reads and start. Twelve hosted import operations delegate file execution and controls to the Data Job Engine. Those routes require both regional bulk and update authority; other protected operations use their declared regional keys. Committed address and override changes reach common reconciliation through captured events. Organization address changes also revisit linked contacts. Policy saves update generations without moving existing records; staff request recalculation when they want changed coverage applied. Traversal commits placements and progress batch by batch, preserves overrides and update locks, and continues through its own captured events. The boundary has important qualifications. Policy reads do not lock settings and criteria into one consistent snapshot, first policy writes can collide, and whole-list saves reset retained rule versions. Replacement clears omitted optional fields, unchanged updates advance versions, and ordinary requests still manage locks without regional history. Recalculation failure settlement is best effort, so exhausted delivery can leave a run stuck in running. New reference checks preserve workspace integrity while older regional references remain tolerated. ## Activities and Tasks Activities and Tasks owns interaction records, outstanding work and the computed timeline for each related CRM record. Activity owns its categories, results, associations and supporting-file entries. Task owns its categories, shared queues, routing and closing attribution. The two service contracts define their record and operation boundaries. The module provides interaction creation, correction, removal and revision reads; configuration maintenance; and contact and organization timeline reads and summaries. Task operations cover work persistence, routing, claiming, release and lifecycle commands, with a separate service dispatcher for workflow callers. Platform executes general workspace views over registered datasets. The local declarations include activity history capture, overdue-task attention and shared queue responsibility. Interaction persistence and requested follow-up insertion commit together. Task checks maintain its lifecycle and routing stamp pairs, and claim arbitration admits at most one committed holder. Enabled attention participates in task transactions, while separately read reconciliation pages can publish older details without a repair deadline. Related-record deletion retains interactions and tasks but can remove all interaction links. Task revision history, assignment eligibility, role-offer discovery and external integration readiness remain unresolved in their existing planning records and examination findings. ## What Is Delegated to Platform and Other Areas Platform defines customization and presentation metadata, evaluates security, owns search projections and communication delivery, and supplies attention, files, numbering and shared work engines. Entities stores the CRM values and selects applicable definitions. Its communication seam includes a narrow insert-only submission grant and bounded request-object write; that exception does not grant general Platform table ownership. Other CRM modules own data quality, regions, bulk work and activities. They use Entities persistence or react to captured events without acquiring another ownership home for its records. Submissions owns future intake processes, and the scoped Entities contracts declare their operations unpublished. Data Quality uses Platform for change dispatch, durable execution, portal identity, attention and workspace lifecycle coordination. CRM supplies the duplicate and merge lifecycle participants. A merge invokes application-owned reference functions inside its execution transaction; external retry and recovery policies require evidence from their owners. Regions uses Entities for stored placements and the Platform Data Job Engine for file execution. Shared libraries supply captured-change dispatch and queue retry; regional handlers retain responsibility for their decision and failure-settlement behavior.