Skip to main content
This page distills the most important internal knowledge for developers working on the Tagada platform. It covers deprecated APIs you should stop using, architecture patterns you must understand, and migrations currently in progress.

​
Deprecated APIs

These APIs have replacements and should not be used in new code. Existing usages should be migrated when touching the relevant files.

​
Plugin SDK (@tagadapay/plugin-sdk)

​
Node SDK (@tagadapay/node-sdk)

​
CRM App

​
Studio App

​
Must-Know Architecture Patterns

These are non-obvious patterns that every developer touching the codebase must understand.

​
CRM App

The CRM is a Vite SPA with React Router — not Next.js. Server-side API and tRPC routers live on the main Tagada app at /api/crm/trpc, not inside crm-app.
Auth and org switching:
  • Clerk provides auth. JWT is passed as Authorization: Bearer to tRPC.
  • Org context is synced via OrgRouteWrapper — when the user switches org, useResetQueries() invalidates all queries to avoid stale data from the previous org.
Funnel dual model:
  • Funnels have both nodes/edges (V2 graph model) and legacy steps (flat list), kept in sync via useFunnelData.
  • Always deep-copy nodes/edges before mutating — they come from React Query cache.
  • Never copy url when cloning steps — the backend recomputes URLs from mount points.
  • Split-test variants each have their own stepConfig.
Plugin lifecycle:
  • instantiate creates a plugin instance but does NOT mount it to a funnel step.
  • The user must explicitly configure and publish. Code should not assume instantiation = live.

​
Studio App

Two operating modes:
  • Embedded (inside CRM iframe): communicates via Builder Protocol (postMessage), skips localStorage hydration to avoid stale data.
  • Standalone (direct URL): authenticated via Clerk, full localStorage persistence for work-in-progress recovery.
DataStore (commerce layer):
  • Vanilla Zustand store (works outside React for island hydration).
  • MockResolver provides static fixtures for design mode. TagadaResolver makes real API calls in live mode.
  • Use registerAction(type, handler) to register action handlers. The old setActionHandler catch-all is deprecated.
Current bundle modes: The modes interactive, esbuild-bundle, and esbuild are legacy and should not be used. Template parsing:
  • parseTemplateFile() accepts 3 formats for backward compatibility: StudioTemplateFile wrapper, legacy { version, template }, and raw FunnelTemplate.
  • Legacy page types upsell / downsell auto-normalize to offer.

​
Active Migration Paths

These transitions are in progress. New code should target the “After” column.