Delivery Hub · Architecture

Sync Topology

Delivery Hub runs across four Salesforce orgs in production. This page is the architecture map — what each node owns, what crosses each hop, what intentionally doesn't, and how a new customer plugs into the chain. Same content for two audiences: the customer who wants to understand the backend they're sitting on, and the prospect deciding whether this is what they want to run.

4
Orgs in the chain
~11s
Bi-directional latency
21+8
Fields synced + bounty
0
Vendor rates ever replicated

Most multi-org Salesforce architectures pick one tradeoff — single-tenant per customer (clean privacy, painful releases) or single-tenant for the vendor (clean releases, leaky privacy). Delivery Hub does neither. Each node owns the facts it's authoritative for, and the sync layer enforces a strict source-of-truth-per-fact invariant: a billing rate set on the vendor mothership cannot accidentally replicate into a customer org because the trigger handler excludes it before the payload is built.

The result: customer-facing surfaces edit work items, the vendor keeps commercial terms private, releases ship to a staging org that runs against real (sanitized) data before any customer sees them, and non-Salesforce stakeholders get a public portal view that's always reading the same data the internal teams are.

The chain

Four nodes, two directions, one source of truth per fact

Each node owns something the others can't replicate. The chain carries work forward; privacy constraints stop specific facts at specific hops.

Customer org
Customer Production
Customer's Salesforce production org
DH managed package installed. Team creates and edits work items, logs hours.
Stores
  • · WorkItem__c
  • · WorkLog__c
  • · NetworkEntity__c
↑↓Bi-directional · ~11s
Relay sandbox
Relay Sandbox
Vendor + customer integration team
Customer prod never connects to vendor mothership directly. Single integration surface.
Stores
  • · WorkItem__c
  • · WorkLog__c
  • · NetworkEntity__c
  • · SyncItem__c
↓Outbound → mothership
Vendor mothership
DH Mothership
Vendor's shared billing org
Billing authority. Invoices live here and ONLY here.
Stores
  • · WorkItem__c
  • · WorkLog__c
  • · NetworkEntity__c
  • · DeliveryDocument__c
↑↓REST read · /push-to-dh write
Public surface
Public Portal
cloudnimbusllc.com
Reads mothership via REST. Strict one-way coupling.
Stores
  • · Mothership REST reads
  • · /push-to-dh writes
Customer's production org
Relay sandbox (shared with customer integration team)
Vendor mothership (billing authority)
Public portal layer
!
Privacy invariant

Vendor billing data lives ONLY on the mothership.

Vendor commercial terms (labor rate, invoice dollar amounts, vendor margin) live ONLY on the mothership. The relay sandbox — which the customer's integration team has access to — intentionally has these fields null / zero / excluded from sync payloads. The data that engineers see on the relay is the customer's own work, not the billing metadata. Invoices (DeliveryDocument__c where TemplatePk__c = 'Invoice') never replicate back into the customer's Salesforce org or the relay. The sync code excludes these fields by design.

Billing objects
DeliveryDocument__c invoices exist on the mothership only. Never pushed to the relay or the customer org.
Rate fields
Labor rate and cost fields on WorkItem / WorkLog get stripped before any outbound sync.
Margin preserved
Customer sees hours and scope. Vendor-side commercial terms stay on the mothership.
Object sync matrix

What flows, what doesn't, and which direction

Each row is one SObject. Columns show the 3 hops in the chain. Privacy-sensitive objects stop at the right edges.

ObjectCustomer ↔ RelayRelay ↔ MothershipMothership ↔ Portal
WorkItem__c
Bi-directionalOutbound only
bi-directional rolling out
Portal push (one-way)
portal reads via REST; writes via /push-to-dh
WorkLog__c
Bi-directionalOutbound only
bi-directional rolling out
Portal read-only
NetworkEntity__c
secrets NOT synced
Bi-directionalBi-directionalPortal read-only
DeliveryDocument__c
split rule: invoices vs. other docs
Split rule
Project docs: bi-directional (proposed) · Invoices: never
Split rule
Project docs: bi-directional (proposed) · Invoices: never
Split rule
Portal read-only for invoices; docs pull for display
SyncItem__c
sync ledger
InternalInternalN/A
Dependency__c
gap — should sync
Gap — should sync bi-directional
Gap — should be bi-directional across all 3 hops. On roadmap.
Gap — should sync bi-directional
Gap — should be bi-directional. On roadmap.
Gap — should sync bi-directional
Gap — portal should surface dependency graph. On roadmap.
Comment__c
gap — should sync
Gap — should sync bi-directional
Gap — comments should thread across orgs.
Gap — should sync bi-directional
Gap — same rationale.
Gap — should sync bi-directional
Gap — threaded comments should surface in portal.
Bi-directionalOutbound onlyPortal push (one-way)Portal read-onlyNot syncedInternalN/AGap — should sync bi-directionalSplit rule
Split rule · DeliveryDocument__c

Invoices stay on the mothership. Other documents should flow.

Today: nothing in DeliveryDocument__c syncs across hops. Future rule: distinguish by TemplatePk__c.

Invoices · mothership ONLY
TemplatePk__c = 'Invoice'. Privacy invariant holds — never replicate to relay or customer.
Other docs · bi-directional (proposed)
Project docs, release notes, onboarding docs. Customers should see documents the delivery team produces.
Field-level sync

WorkItem__c: what crosses, what stays

Source of truth is the trigger handler in the DH managed package. Anything not in this list does not propagate.

Auth + security

Three moving parts, zero shared secrets across the chain

Each pairwise hop has its own credential set stored on the NetworkEntity record. Loop prevention is stamped at the origin and checked at every receiver.

1
API key per NetworkEntity
Each org holds a per-partner NetworkEntity__c record containing ApiKeyTxt__c, HmacSecretTxt__c, and IntegrationEndpointUrlTxt__c. Secrets never replicate across the sync boundary.
  • ApiKeyTxt__c
  • HmacSecretTxt__c
  • IntegrationEndpointUrlTxt__c
2
HMAC-signed payload
Every outbound sync signs the serialized JSON payload with the receiver's shared secret. Receiver recomputes and compares. Tamper-evident by design.
  • X-Signature: HMAC(secret, payloadJson)
3
Loop prevention
Origin stamps X-Global-Source-Id from the SyncItem's GlobalSourceIdTxt__c. On echo-back, the receiver detects its own origin and drops the update — preventing infinite ping-pong.
  • X-Global-Source-Id
  • SyncItem.GlobalSourceIdTxt__c
// Outbound request envelope
POST {NetworkEntity.IntegrationEndpointUrlTxt__c}
Authorization: Bearer {NetworkEntity.ApiKeyTxt__c}
X-Signature: {HMAC-SHA256(HmacSecretTxt__c, payloadJson)}
X-Global-Source-Id: {SyncItem.GlobalSourceIdTxt__c}
Content-Type: application/json
// Receiver validates all 4 before accepting
Known gaps

What we're actively fixing

Every gap is tracked with a concrete mitigation path. Nothing is mystery-state.

1

WorkLog race on receiver

In flight
Problem
A new WorkLog__c can arrive at the receiver before its parent WorkItem__c has finished propagating. Insert fails because the parent lookup is not yet resolvable.
Fix
DH adds a Queueable retry on the receiver. WorkLogs that fail on parent-lookup enqueue, re-try on a short delay, and succeed once the parent lands.
2

No portal write-back for UI edits

Planned
Problem
Edits made in the public portal UI don't round-trip to the mothership. Portal is read-dominant; writes are limited to /push-to-dh creation flows.
Fix
Future arc: portal edit → /push-to-dh patch → mothership update → normal outbound propagation to relay + customer. Needs conflict resolution policy first.
3

Dependency__c not bi-directional

Planned
Problem
Dependencies created against a customer work item stay org-local. They don't propagate to the mothership or portal, so the delivery team has no downstream visibility into customer-set dependency graphs — and vice versa.
Fix
Extend sync engine to include Dependency__c across all 3 hops. Same loop-prevention + auth pattern as WorkItem__c. Needed for cross-org dependency graphs and Gantt parenting.
4

Comment__c not bi-directional

Planned
Problem
Comments written in either org stay local. Customer comments don't surface in the mothership for the delivery team; delivery-team comments don't surface back to the customer. Threaded conversation is fragmented.
Fix
Sync Comment__c bi-directional across all 3 hops. Consider opt-in per-comment privacy flag if internal-only comments are needed.
Onboarding

Five steps to join the chain

Install the managed package, exchange credentials, verify round-trip. The first-sync test is the gate — if a WorkItem round-trips, the chain is live.

  1. 1

    Install the DH managed package

    Owner: Customer SF admin
    Customer installs the Delivery Hub managed package in their production Salesforce org. Brings over WorkItem__c, WorkLog__c, NetworkEntity__c, SyncItem__c, plus the trigger handlers that power sync.
  2. 2

    Provision NetworkEntity records

    Owner: Vendor
    Vendor creates paired NetworkEntity__c records in both orgs (customer + relay). Each points at the other's integration endpoint. One key per pairwise direction.
  3. 3

    API key + HMAC secret exchange

    Owner: Vendor
    Generate and populate ApiKeyTxt__c and HmacSecretTxt__c on both NetworkEntity records. Keys exchanged via secure channel — not in source control or chat.
  4. 4

    Remote Site Settings on both sides

    Owner: Customer SF admin
    Each org adds the counterpart's integration domain to Remote Site Settings. Without this, outbound callouts fail before auth. One of the top onboarding miss-steps.
  5. 5

    First sync test

    Owner: Vendor + customer admin
    Create one WorkItem__c in the customer org. Verify it lands in the relay within ~15 seconds, then in the mothership. Edit it in the relay and confirm the edit flows back. Round-trip confirms the chain is live.
Future state

What fully bi-directional looks like

The chain is healthy end-to-end on the customer-to-relay hop. Completing bi-directional behavior on the remaining hops unlocks true multi-surface editing.

Relay ↔ Mothership: full bi-directional

Next minor
Today · Outbound only — relay pushes to mothership.
Future · Mothership pushes WorkItem and WorkLog edits back to the relay. Same auth, same loop-prevention, same privacy excludes. Already scaffolded; rolling out next minor.

Portal edits round-trip

Future arc
Today · Portal reads the mothership. Writes only via /push-to-dh creation flows.
Future · Every portal UI edit patches the mothership, which propagates back through the chain. Unlocks 'edit anywhere, see it everywhere.'

Multi-customer chain scaling

Productization
Today · Onboarding is partly manual: vendor creates NetworkEntity records and swaps keys.
Future · Self-service onboarding wizard. Customer installs DH, enters a pairing code, chain joins itself. Each customer is one more node pair on the relay.

Dependency__c + Comment__c sync

Planned
Today · Dependencies and comments are org-local today.
Future · Bi-directional sync across all 3 hops so customer-set dependencies surface in mothership and portal, and comments thread across the chain.
For customers

Installing Delivery Hub plugs your Salesforce org into the chain. Your team works inside your own org; work items flow to the relay for triage, then to the mothership for billing. Your production data stays yours — nothing vendor-side replicates back.

For prospects

This is what you're evaluating. Free managed package, no per-seat fees, explicit privacy invariants enforced at the trigger handler. Install into a sandbox, run the round-trip test, decide.

For engineers

Source of truth for field-level sync is the trigger handler in the DH managed package. Privacy excludes are enforced at the trigger handler, not downstream. If a field is listed, it syncs. If not, it doesn't.

Install Delivery HubDelivery Hub overviewLatest release roundup