Create a contact
What It Does
Creation establishes one continuing person identity together with the information needed to use it: names, contact points, preferences, affiliations and permitted customer-defined values. For example, a coordinator adds Ruth Kim as a member-firm representative and expects the person, employer connection and initial responsibilities to describe the same committed result.
Our reading is that the sequence matters because validation, files, numbering and dependent projections cross different boundaries. The local aggregate can roll back as one unit; an allocated number or a prepared file has its own recovery behavior. A successful form submission establishes the contact, while search and region updates may still be pending.
What Starts It
A membership coordinator submits the configured person form, or an integration calls contact creation. The submitted names, details and affiliations enter one creation request. A client identity can support recognized replay; an idless submission does not acquire that guarantee. Reaching the request boundary does not mean duplicate checks or persistence have succeeded.
The Flow
The diagram shows the sequence and service seams. Each synchronous stage waits for its result, while captured-event, queue and scheduled stages can run after the originating request has returned. The hop descriptions below identify the write and failure boundary, so the last arrow must not be mistaken for one atomic transaction across every participant.
Hop by Hop
1. Console contact editor
The editor turns the selected classification and configured fields into one creation intent. A reserved client identity connects an ambiguous response to a later read, so retry recovery can ask whether Ruth already exists before issuing another creation. The form holds the draft until the service confirms the result.
2. CRM dispatcher and Entities route
The dispatcher and route establish application reach and create authority before interpreting the business payload. They also evaluate the narrowly separate duplicate override grant. Field problems or an attempted lock assignment are reported before persistence, so an invalid form cannot partly establish the person.
3. Entities create composition
Create composition compares the supplied identity with the validated request fingerprint. Matching content can recover the contact already committed by a competing attempt; different content cannot silently adopt that earlier person. This stage is a synchronous replay check, not a search-based duplicate decision.
4. Data Quality duplicate guard
The duplicate guard asks Data Quality whether configured blocking conditions identify possible existing people. A refusal returns candidates and whether override is available. An override requires both authority and a reason, so recognizing a suspected duplicate remains distinguishable from establishing a different person deliberately.
5. Shared record-asset pipeline
The asset stage prepares permanent photo and file-valued custom-field copies before the record transaction. It supplies stable file references to the later write. This seam cannot be rolled back by deleting a database row, so abandoned copies require the asset cleanup mechanism if the remaining create fails.
6. Entities persistence (one transaction)
Persistence assembles and validates the contact aggregate in one transaction. It coordinates spouse reciprocity, typed details, affiliations, eligible responsibility assignments and selected shared defaults. Number allocation is independently spent, while owner and owned business values either commit together or disappear together on rollback.
7. Database change capture
Database capture builds the contact’s attributed revision and change event as part of creation. A spouse changed reciprocally receives a separate subject revision. Missing attribution therefore prevents the creation from committing rather than leaving a contact whose provenance cannot be reconstructed.
8. Entities route
The route requests an early dispatch after commit. It does not reopen the successful creation if the request to dispatch fails. The durable event remains available to scheduled publication, separating the response to the coordinator from the time dependent services receive the change.
9. CRM change-event consumers
Independent consumer messages let compliance, region, search and duplicate reactions succeed or retry separately. Some handlers reread current committed data; search uses the captured snapshot contract. The person already exists while these projections catch up, and one handler’s retry is not another creation.
When Something Fails
Hop 1 — Console contact editor
The failure boundary is: On an ambiguous result, read that identity before offering another create attempt. The remaining work or data is: No partial business write remains. The creator sees form or recovery feedback.
Hop 2 — CRM dispatcher and Entities route
The failure boundary is: Return field validation errors or an authorization refusal before persistence. The remaining work or data is: No partial business write remains. The caller receives the result.
Hop 3 — Entities create composition
The failure boundary is: A conflicting existing identity is refused; a recognized retry returns the prior contact. The remaining work or data is: No partial business write remains. The caller receives the result.
Hop 4 — Data Quality duplicate guard
The failure boundary is: Return duplicate candidates and override availability without creating the contact. The remaining work or data is: No partial business write remains. The duplicate dialog shows the refusal.
Hop 5 — Shared record-asset pipeline
The failure boundary is: Refuse invalid or failed asset preparation before saving the record. The remaining work or data is: Prepared copies may remain until abandoned-asset cleanup. Asset cleanup logs show deferred removal.
Hop 6 — Entities persistence (one transaction)
The failure boundary is: Roll back the aggregate on failure and return the detected problems. The remaining work or data is: An allocated number is spent, and prepared files may await cleanup. The caller receives the result.
Hop 7 — Database change capture
The failure boundary is: Missing required attribution prevents capture and rolls back creation. The remaining work or data is: No partial business write remains. Contact history exposes the committed revision.
Hop 8 — Entities route
The failure boundary is: Ignore a failed nudge and rely on scheduled dispatch. The remaining work or data is: Post-commit reactions can be delayed. Dispatcher logs show publication attempts. A later attempt can be required; the scheduling or publication boundary does not establish an immediate user-visible completion.
Hop 9 — CRM change-event consumers
The failure boundary is: Retry failed handler messages through SQS and dead-letter after five receives. The remaining work or data is: The contact persists while dependent compliance, region or search state may lag. Consumer logs and the dead-letter queue identify failed handlers. This failure is downstream of committed input; operators investigate its own delivery rather than treating the caller’s original save as failed.
Repeats and Races
The supplied contact identity and validated fingerprint provide replay recognition. A matching retry returns the earlier committed person, while changed content under that identity conflicts. An idless request lacks that replay recognition. After an uncertain response, this contract does not establish a reliable identity-based retry for that request; staff must inspect saved records rather than assume another create will be recognized.
Creates can contend on spouse pairs, primary email or destination organizations. Organization locking coordinates first-contact roles under simultaneous joins. The separately allocated number can leave a gap after rollback; this is not evidence that a missing contact once committed. Prepared files also have a cleanup boundary independent of replay.
What Is Observable
The creator sees form or recovery feedback. The caller receives the result. The duplicate dialog shows the refusal. Asset cleanup logs show deferred removal. Contact history exposes the committed revision. Dispatcher logs show publication attempts. Consumer logs and the dead-letter queue identify failed handlers.
The person or initiating caller sees the synchronous result at its own boundary. Captured history establishes committed local changes; logs, durable job state and queue outcomes explain remaining work. A successful database change, accepted downstream request and completed delivery are different observations and must be investigated through the component that owns each one.
Open Design Questions
Replay recognition applies to contact creation and depends on a stable identity and matching fingerprint. It is not a generic guarantee for organization or catalogue creation. Dedicated browser proof of all ambiguous-response recovery remains limited by the existing acceptance findings; the design explains the built recovery path without claiming a complete delivery guarantee.