Upbeat Data Bridge: The Full Entity Map (Both Strokes)

Extends the drivers arc to its logical end-state: everything in Upbeat finds a home in the Agend suite, flowing down (Upbeat → Agend) via source drivers and up (Agend → Upbeat) via the write-back outbox — so the Agend product suite acts as the data bridge, and spokes (Agend Pro WordPress, portal, mobile, client-built tools) never touch Upbeat at all. Sources: .docs/reports/upbeat-domain-map.md (endpoint-level inventory, §1.1–1.10 + driver phasing §4), writeback-two-way-sync.md (up-stroke machinery, tiers W1–W4), ADR-001 (custom objects for the long tail). Status: PROPOSED MAP · 2026-07-07

1 · The bridge model

              DOWN STROKE                          UP STROKE
   Upbeat ──[source drivers: Singer taps,──▶  Agend suite  ──[transactional outbox,
             watermark + content-hash]         (Supabase hub)  reverse-map, echo guards]──▶ Upbeat

   SPOKES (never touch Upbeat): Agend Pro WP · portal · mobile · client tools · widgets
                     ▲ read via /v1 API ▼ write via /v1 API (hub-first, async propagate)

Every entity gets a direction class, which decides what machinery it needs:

The Oracle class, spelled out (asked directly 2026-07-08): the outbox governs mastered writes; it does not forbid synchronous calls where Upbeat is the computation engine. Canonical example: cart pricing — the legacy build creates a draft invoice per cart (Session::create_new_invoice → add_product_to_invoice) so Upbeat returns the real member-specific price, and checkout totals are the CRM's. That flow survives intact; what changes is who makes the call: the hub's connector (same OAuth/token machinery as the drivers), never the client's WordPress. Natural API home: the gateway cart's checkout/simulate route. Required hygiene (the async-proposal lesson): timeout + "price confirmed at checkout" fallback, quote caching in the hub, and a shrink path — price groups/price points already sync down, so each pricing rule mirrored into the hub removes a synchronous dependency. Strangler pattern, applied to computation.

2 · The map — every Upbeat domain, its Agend home, both strokes

WP column = what the legacy WordPress build imports this into today (the thing the bridge replaces).

Coverage check: every object class in the legacy connector's inventory (~45 read families, ~45 write methods) lands in exactly one row above. The long tail (12, 13) needs no bespoke drivers if O4 (generic driver → custom objects) is built — that single capability closes the map.

3 · How "both ways" works per entity (the storage contract)

1. One field-ownership registry per entity (extends the pattern shipped in crm-loader.ts for contacts): each field is Upbeat-owned (down only, read-only in Agend UIs), Agend-owned (up only, ingest never overwrites), or shared (both strokes + conflict queue per writeback doc §7).
2. Down stroke = the existing driver pattern unchanged: Azure-AD auth, paged fetch, watermark delta, content-hash skip, per-account Inngest orchestration. New entities are new drivers (or generic-driver configs), not new architecture.
3. Up stroke = the writeback outbox unchanged: hub-first write, transactional enqueue, ordered operation groups, echo prevention via content-hash convergence. New entities are new WriteBackOperation types + reverseMap rules, not new architecture.
4. The strangler contract for Agend Pro WP: per entity row, once BOTH strokes are live, the WP integration flips from Iugo_Membership_Kiosk_API to the Agend API — and that slice of the proprietary plugin retires. The bridge map is therefore also the plugin retirement schedule (and the code-protection sunset schedule).
5. Ledger-class nuance (row 9): CPD is the clearest case where Agend originates data — LMS course completions must flow UP into Upbeat's CPD ledger. Append-only ops avoid the conflict problem entirely; this is the easiest "up" class after profile updates.

4 · The events decision: sync vs migrate (O3)

The hardest driver (~40% bespoke per the pilot doc) vs a native module that already exists. Decide per this framework before W4 work starts:

Recommendation to evaluate first: a hybrid — migrate event management to native Events, keep a thin financial up-stroke (registrations → Upbeat invoices via the already-planned W2 machinery). That deletes the events driver and W4's registration write-back, keeping only money flows Upbeat genuinely needs. Needs a client-workflow audit (who touches events in Dynamics today?) before committing.

5 · Sequencing (merging the domain map's phases with write-back tiers)

6 · Client configurations: the bridge is optional per client

Because the hub is the system of record natively, Upbeat is a configuration, not a dependency. The same suite (and the same thin WordPress plugin + widgets + API) serves three client types — only the back-of-hub differs:

Migrated and native clients skip this entire map: no drivers, no field ownership, no conflict queue, and every write capability is available immediately (W1–W4 exist only because of Upbeat). One WordPress build serves all three (opportunity O6, platform-opportunities.md).

7 · What this map is

It is the answer to "can everything in Upbeat live in Agend?" — yes: 12 domains have native homes, 2 ride custom objects, and one (events) has a decision to make that might be cheaper than anyone assumed. It is simultaneously the driver roadmap, the write-back roadmap, the WP plugin retirement schedule, and the sunset plan for code protection — one map, four programmes aligned. And per §6, it is the maximal case: only bridged clients need any of it.

What this map is not is a mandate to rebuild Upbeat's authoring surfaces — see strategic-posture-upbeat.md for the standing answer to "are we replicating Upbeat?" and the operating rule that governs every entity flip.