Crescendo.ai Phase 1 — Salesforce routing engine. Edit any input on the left to see how the engine would classify the Contact, who would own it, and what side effects would fire. Mirrors ContactRouter.classifyOne on main as of the post-Plans-1-4 build.
Live decision flow for the record on the left. Green = active routed path; red = active triage / HOLD terminal; dimmed = inactive branches. Click any expandable path node (T, A, D, E) to inspect its sub-tree; the sub-tree containing the active terminal auto-expands.
Every node the router can visit, in evaluation order. No scenario highlighting — this is the full decision surface, derived from docs/v3-architecture-plan.md and ContactRouter.cls. Six paths: TAGGED_ACCOUNT → CUSTOMER_ACCOUNT → ACTIVE_DEAL → ACCOUNT_BDR → ROTATION_NEW_ACCOUNT / ROTATION_BDR_ONLY. First match wins; fall-through is explicit per gate.
Routing_Path__cRouting_Exception__cCadence enrollment — ACCOUNT_BDR, ROTATION_NEW_ACCOUNT, ROTATION_BDR_ONLY paths only. Flow re-reads Contact after Apex returns, then calls assignTargetToSalesCadence with Routing_Config__mdt.Default.NonTarget_Cadence_Id.
BDR Task — TAGGED_ACCOUNT only, and only for Active Target accounts where BDR_Owner__c is populated and active. No other path creates a Task.
In-batch buying-group continuity — if ≥2 Contacts in the same route() batch share an Account, the first Contact classifies normally; subsequent Contacts on that Account copy the first Contact's Routing_Path__c, OwnerId, and cadence decision without re-running classification or rotation.
Account.BDR_Owner__c invariant — written only by ROTATION_NEW_ACCOUNT and ROTATION_BDR_ONLY. ACCOUNT_BDR does not write it (already aligned). No other path touches it.
Contact_Routed__e publish — fired on every successful routed terminal (TAGGED_ACCOUNT, CUSTOMER_ACCOUNT, ACTIVE_DEAL, ACCOUNT_BDR, ROTATION_NEW_ACCOUNT, ROTATION_BDR_ONLY). Clay subscribes; no per-BDR webhook fan-out. Not fired on HOLD/UNROUTED outcomes.
End-to-end inventory of the routing engine. v3 architecture is live in routing-dev as of 2026-05-21. Phase 1 = "Flow detects, Apex decides". Staging is still empty — engine is ready for staging migration. Verified via sf apex run test and sf org list metadata diff.
ContactRouter + RotationService) and one thin record-triggered Flow (Contact_AfterSave_RouteOnMQL, ~8 elements). All v1 Apex classes — PoolClaimHandler, RoutingTriggerGate, RoutingMaintenanceBatch, ContactRouterFlow — are retired and removed from the codebase. Staging has not yet been touched.
Routing_Config.Default is the only Custom Metadata record currently in the repo. Any Rep_Roster__mdt records added in routing-dev during testing must be retrieved before staging deploy: sf project retrieve start --metadata "CustomMetadata:Rep_Roster.*,CustomMetadata:Routing_Config.*" --target-org routing-dev. Never recreate MDT records manually in staging — always deploy from source.
All "Missing" items below are verified-complete in routing-dev (ContactRouterTest + RotationServiceTest passing, all routing Flows deployed, Routing_Config.Default MDT record loaded). "Missing" refers strictly to the staging org state.
The engine is a deliberate hybrid: Flow detects events, Apex makes routing decisions. This isn't a Salesforce-versus-no-code preference — it's a response to four properties Flow cannot deliver at the volume and concurrency this engine sees.
Record-triggered detection (insert/update events), simple in-memory field stamps (e.g. Contact_BeforeSave_StampMQL), the trigger-gate decision, the $Permission.Bypass_Automation kill switch, and entry-filter expressions admins can read.
Path classification (TAGGED_ACCOUNT → CUSTOMER_ACCOUNT → ACTIVE_DEAL → ACCOUNT_BDR → ROTATION_NEW_ACCOUNT / ROTATION_BDR_ONLY), round-robin rotation with locking, bulk-safe counter math, per-record error handling, in-batch buying-group continuity, platform-event publish (Contact_Routed__e).
SELECT ... FOR UPDATE row locking
Flow has no equivalent. Two concurrent MQLs in the same Region would read the same Rep_Rotation_Counter__c value and assign the same rep — a guaranteed double-assignment race at any meaningful inbound volume. The mitigation (queueable serialization) is Apex-only.
FOR UPDATE, advances it in-memory across the whole batch, and writes once. Flow either updates each iteration (DML explosion against the 150-DML governor) or skips and recomputes (logic explosion). Neither survives a 200-record HubSpot sync burst.
Routing_Path__c="UNROUTED_ERROR" + Routing_Last_Error__c, and continues. Flow's fault model is per-element, not per-record-in-collection. Approximating it requires invoking a subflow per record — which destroys the bulk efficiency you just won back.
System.runAs, deterministic assertions, and a hard 85% coverage gate in the deploy pipeline. Tests like pathE_failedBdrCheck_doesNotBurnAESlot verify specific edge cases in concurrent rotation. Flow has no equivalent — change validation is manual debug runs in a sandbox.
The v3 engine has exactly two production Apex classes: ContactRouter (main Invocable router, entry point for the thin Flow) and RotationService (locked round-robin utility, also exposed as an @InvocableMethod for Phase 2 Flow reuse). Retired v1 classes (PoolClaimHandler, RoutingTriggerGate, RoutingMaintenanceBatch, ContactRouterFlow) are removed from the repo. None of the v3 classes are in staging yet — coverage target ≥85% on ContactRouter.
| Class | Purpose | Status |
|---|---|---|
| ContactRouter | Main router — classifies MQL Contact into one of 13 Routing_Path__c values, assigns OwnerId, stamps Account.BDR_Owner__c on rotation paths, publishes Contact_Routed__e, inserts Routing_Exception__c on unrouted outcomes. @InvocableMethod entry point called by Contact_AfterSave_RouteOnMQL. | Missing |
| RotationService | Locked round-robin utility — SELECT ... FOR UPDATE on Rep_Rotation_Counter__c, bulk-safe counter math, checkOnly mode for pre-flight eligibility checks. @InvocableMethod also exposed for direct Phase 2 Flow calls. | Missing |
| ContactRouterTest | Test class — covers all 13 paths, bypass-permission run, in-batch buying-group continuity, concurrency pre-check (failed BDR check does not burn AE slot). | Missing |
| RotationServiceTest | Test class — round-robin sequencing, checkOnly mode, roster eligibility filtering. | Missing |
These four Flows are the Phase 1 routing engine surface. Contact_AfterSave_RouteOnMQL is the "thin Flow" (~8 elements): checks $Permission.Trigger_Routing → checks $Permission.Bypass_Automation → calls ContactRouter.route → branches on BDR paths → re-reads Contact → assignTargetToSalesCadence with fault path. No path classification inside the Flow. Full spec in docs/production-flows.md.
| Flow | Trigger / Action | Status |
|---|---|---|
| Contact_AfterSave_RouteOnMQL | Contact after-save · $Permission.Trigger_Routing gate → $Permission.Bypass_Automation kill-switch → invokes ContactRouter.route → cadence enrollment for BDR paths (ACCOUNT_BDR, ROTATION_NEW_ACCOUNT, ROTATION_BDR_ONLY) with fault path | Missing |
| Contact_BeforeSave_StampMQL | Contact before-save · stamps MQL_Stamped_At__c + lifecyclestage__c on transition to "Marketing Qualified Lead" | Missing |
| RoutingException_BeforeSave_StampResolution | Routing_Exception__c before-save · stamps Resolved_At__c / Resolved_By__c when Status__c transitions to Resolved | Missing |
| Task_AfterInsert_DetectPositiveSignal | Task insert · detects positive engagement signal on Contact, stamps signal fields per docs/positive-signals.md | Missing |
force-app/main/default/flows/ but are not part of the Phase 1 routing engine: Account_Before_Save, Contact_After_Save, Contact_AfterSave_DQFeedback, Task_Before_Save, Task_After_Save, Event_After_Save_Update_Last_Interaction_Date, Opportunity_Update_Contact_to_Sales_Qualified_Lead_Upon_Creation, and others. Decide per-flow whether they ship with the routing engine or are managed separately.
| Object | Purpose | Status |
|---|---|---|
| Rep_Roster__mdt | Custom Metadata Type — AE/BDR roster keyed by Region + Segment. | In repo |
| Routing_Config__mdt | Custom Metadata Type — single Default record holds pool user-id, cadence id, triage owner, and config thresholds. | In repo |
| Rep_Rotation_Counter__c | Counter rows for round-robin rotation. Reads use SELECT … FOR UPDATE to serialize concurrent transactions. | In repo |
| Routing_Exception__c | Triage object (auto-number RX-{0000}) — replaces v1/v2 admin Tasks. Required fields: Contact__c, Account__c, Failure_Reason__c (picklist), Status__c, Error_Detail__c, Resolution_Notes__c, Resolved_At__c, Resolved_By__c, Routed_At__c. Owned by the Routing_Triage queue by default. | In repo |
| Contact_Routed__e | Platform Event published by ContactRouter. Clay subscribes to this single endpoint instead of per-BDR webhooks. | In repo |
Routing-engine fields verified against force-app/main/default/objects/. The repo contains additional non-routing fields (lead-score, HubSpot sync state, etc.) not listed here.
| Field | Type / purpose | Status |
|---|---|---|
| lifecyclestage__c | Text (all lowercase — gotcha). Gate value: "Marketing Qualified Lead". HubSpot-owned; router reads, never writes. | In repo |
| MQL_Stamped_At__c | DateTime — set by Contact_BeforeSave_StampMQL, drives re-MQL window. | In repo |
| Routing_Path__c | Text(40) — stable enum stamped on every routing pass. 13 values: HOLD, TAGGED_ACCOUNT, CUSTOMER_ACCOUNT, ACTIVE_DEAL, ACCOUNT_BDR, ROTATION_NEW_ACCOUNT, ROTATION_BDR_ONLY, UNROUTED_BAD_DATA, UNROUTED_TAGGED_NO_OWNER, UNROUTED_NO_OWNER, UNROUTED_NO_REGION, UNROUTED_NO_AE, UNROUTED_NO_BDR, UNROUTED_ERROR. | In repo |
| Routing_Last_Run__c | DateTime — timestamp of last router pass. | In repo |
| Routing_Last_Error__c | Long Text — preserved for org compatibility; triage now goes to Routing_Exception__c in v3. | In repo |
| Routing_Cadence_Error__c | Text — cadence-enrollment fault captured by Flow. | In repo |
| On_Hold__c | Checkbox — pre-route gate; exits cleanly with path HOLD. | In repo |
| Last_Signal_Date__c | DateTime — positive-signal detection (Task_AfterInsert_DetectPositiveSignal). | In repo |
| Signal_Type__c | Text — signal category from Task disposition. | In repo |
| Record_source__c | Text (lowercase 's' — gotcha). Inbound source tag from HubSpot. | In repo |
| Record_source_detail_1__c | Text (lowercase — gotcha). Source detail tier 1. | In repo |
| Field | Type / purpose | Status |
|---|---|---|
| Account_Status__c | Picklist — drives path selection (Tagged, Customer, Active Deal, BDR, Rotation). | In repo |
| Is_Tagged_Account__c | Formula — true for Active Target / Active Conversion / Active Velocity. Canonical flag for TAGGED_ACCOUNT path. | In repo |
| Target_Account__c | Formula — narrower: true only for "Active Target Account". Used to decide BDR manual-outreach Task; not the routing gate. | In repo |
| Region__c | Picklist — territory key; joins with Segment to Rep_Roster__mdt. Blank → UNROUTED_NO_REGION. | In repo |
| Revenue_Range_Segments__c | Picklist — values: "Velocity ($50M)" / "Enterprise ($50M-$500M)" / "Strategic ($500M+)". | In repo |
| BDR_Owner__c | Lookup (User) — always equals the most recent BDR the router assigned to a Contact on this Account. Both ROTATION paths stamp it. | In repo |
| Do_Not_Route__c | Checkbox — Account-level routing block; exits with path HOLD. | In repo |
| Cooldown_End_Date__c | Date — set by maintenance sweep (Phase 2). Sweep-only; never blocks routing in Phase 1. | In repo |
| AE_Meeting_Link__c | Formula = Owner.Meeting_Link__c. Do not recreate. | In repo |
| Component | Purpose / kill-switch role | Status |
|---|---|---|
| Routing_Engine_Service | Permission Set — engine runtime permissions. Grants object/field CRUD for Contact, Account, Rep_Rotation_Counter__c, Routing_Exception__c, Contact_Routed__e. Also grants Trigger_Routing. Assign to the integration user that runs routing. | In repo |
| Routing_Trigger_Users | Permission Set — primary kill switch. Grants Trigger_Routing to trigger-context users. The Flow's element-zero gate checks this permission (default-deny). Unassigning from the trigger user halts routing immediately with zero blast radius. | In repo |
| Routing_Bypass_All | Permission Set — emergency stop. Grants Bypass_Automation. Mass-assign to halt all record-triggered routing Flows within seconds; targeted unassignment to resume. No deploy required. | In repo |
| Trigger_Routing | Custom Permission — checked by element-zero of every routing Flow ($Permission.Trigger_Routing). Default-deny: a user without this permission exits the Flow cleanly. | In repo |
| Bypass_Automation | Custom Permission — checked immediately after the trigger gate in every routing Flow ($Permission.Bypass_Automation). Granted by Routing_Bypass_All. | In repo |
Only Routing_Config.Default is checked into force-app/main/default/customMetadata/. Rep_Roster__mdt rows (AE/BDR dev users) exist in routing-dev but are not yet retrieved into source control — retrieve and commit before staging deploy.
| Record | Values / notes | Status |
|---|---|---|
| Routing_Config.Default | Cooldown_Days=30, Inactive_Days=30, Signal_Expiration=30, AE_Dedupe=7. NonTarget_Cadence_Id__c, Prospecting_Pool_User_Id__c, and Unrouted_Triage_Owner_Id__c are null — populate before routing runs end-to-end. Note: legacy Routing_Trigger_User_Ids__c field is retired; do not reference it. | In repo |
| Rep_Roster__mdt rows | AE and BDR dev-user records loaded in routing-dev via seed script (scripts/apex/seed_routing_dev.apex). Not yet in source control. Production roster must cover all expected Region × Segment combinations or missing combos route to UNROUTED_NO_AE / UNROUTED_NO_BDR. | Dev only |
sf project retrieve start --metadata CustomMetadata to pull Rep_Roster rows into source control, review for PII (replace user Ids with prod values), then re-deploy. Production roster must fill all Region × Segment combinations expected in inbound traffic.
Target_Account__c from OR(NOT(A), NOT(B)) (true for every non-blank status) to AND(non-blank, ISPICKVAL("Active Target Account")). Any existing report, list view, or dashboard filtered on Target_Account__c = true will return fewer rows after deploy. Inventory and notify owners.
ActionCadenceTracker model). Build the production ActionCadence for non-Target outbound, then wire its Id into Routing_Config.Default.NonTarget_Cadence_Id. Assign the Sales Engagement Basic PSL (99 free seats) to the user context the routing Flow runs under.
Routing_Trigger_Users permission set (grants the Trigger_Routing custom permission) to the HubSpot sync user. The gate is default-deny — a user without this PSL gets no routing at all. This PSL is also the preferred rollback: unassigning it stops routing for that user immediately, no deploy required.
Routing_Config.Default needs production Ids for Prospecting_Pool_User_Id__c (service account that holds unowned Accounts) and Unrouted_Triage_Owner_Id__c (the Id of the Routing_Triage queue — deployed from force-app/main/default/queues/Routing_Triage.queue-meta.xml; confirm the queue Id in staging after deploy before wiring it in).
Routing_Exception__c records (auto-number RX-{0000}) owned by the Routing_Triage queue — not admin Tasks. Before go-live: (a) confirm the Routing_Triage queue is deployed and RevOps team members are queue members; (b) verify the Routing_Exception__c App tab exists; (c) build list views for Open and Investigating statuses filtered to the queue. Sales reps must never see triage items in their Task lists.
Account_Status__c initial values ride the HubSpot → Salesforce production data load. There is no standalone Apex backfill. Confirm the data load includes this mapping before flipping the gate.
AccountId. HubSpot owns Contact → Account matching. Verify the integration is populating AccountId before routing goes live.
ContactRouter, ContactRouterTest, RotationService, RotationServiceTest. Run the full suite as part of the pipeline validation step (--test-level RunLocalTests). Tests must use System.runAs with a user whose Profile lacks Bypass_Automation; a dedicated bypass-path test must assert no routing occurred.
All deploys go through the CI/CD pipeline (branch → PR → validation → merge). Claude Code does not deploy to staging. The order below is what the pipeline / human operator should follow.
force-app/main/default/customMetadata/ must contain all Rep_Roster__mdt and Routing_Config__mdt records before the pipeline runs. If any records were added to routing-dev after the last retrieve, pull them now and commit. Production Ids (users, queue) are swapped into the files before pipeline deploy — do not hard-code dev sample values.Rep_Roster__mdt, Routing_Config__mdt, Rep_Rotation_Counter__c, Contact_Routed__e, plus the new Contact and Account custom fields. Target_Account__c formula gets redeployed in this step.$Permission.Bypass_Automation / $Permission.Trigger_Routing.ContactRouter, ContactRouterTest, RotationService, RotationServiceTest. Pipeline must run tests with --test-level RunLocalTests and verify ≥85% coverage on both production classes.Rep_Roster__mdt and Routing_Config__mdt records with production user-ids substituted in, not dev sample values. At this point do not assign Routing_Trigger_Users to the sync user yet — that's the default-deny gate, flipped in step 6.Routing_Engine_Service and Routing_Trigger_Users. Assigning Routing_Trigger_Users is the act that turns the gate on — do this only after data validation in step 7. The Sales Engagement Basic PSL must also be assigned for cadence enrollment to function.Contact_Routed__e subscription is configured in Clay.$Permission.Trigger_Routing custom permission, granted via Routing_Trigger_Users PSL. If the PSL was assigned in step 6, the gate is live — no additional metadata deploy is needed. Verify in staging with a SOQL check that the PSL assignment exists.Routing_Path__c is set, owner is correct, Contact_Routed__e fires. Then test a Path E unowned Account to confirm round-robin AE selection.Remove the Routing_Trigger_Users permission set from the integration user. The Flow's element-zero check on $Permission.Trigger_Routing fails and routing exits cleanly — no routing for that user. No deploy required. Restore by reassigning the PSL. This is the standard rollback.
Assigns the Bypass_Automation custom permission. The Flow's second gate fires and halts routing for all holders within seconds — no deploy required. Use when something is firing wrong for multiple users and you need an immediate broad stop. Targeted PSL unassignment to resume.
Set up once. Every push to the configured branch will rebuild and publish.
routing_simulator.html to a GitHub repolead-routing (which is private), consider a small public-ish or org-private repo just for the simulator HTML so Netlify can pull it.main).index.html/ → /routing_simulator.html in a _redirects file.