feat(webapp): make the default realtime backend configurable

Author: ericallam

.server-changes/realtime-backend-default-env.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+Add a `REALTIME_BACKEND_DEFAULT` env var to choose the default realtime backend (`electric`, `native`, or `shadow`) for environments whose org has no per-org override. Defaults to `electric`, so existing behavior is unchanged.

apps/webapp/app/env.server.ts

@@ -374,6 +374,8 @@ const EnvironmentSchema = z
 
     // Master switch for the native realtime backend; off = Electric serves everything, publishes no-op.
     REALTIME_BACKEND_NATIVE_ENABLED: z.string().default("0"),
+    // Default backend when an org has no `realtimeBackend` override and no global flag row is set.
+    REALTIME_BACKEND_DEFAULT: z.enum(["electric", "native", "shadow"]).default("electric"),
     // Live long-poll backstop hold (ms); matches Electric's ~20s cadence.
     REALTIME_BACKEND_NATIVE_LIVE_POLL_TIMEOUT_MS: z.coerce.number().int().default(20_000),
     // Jitter ratio on the live-poll hold (0.15 = ±15%) to avoid synchronized refetch herds.

apps/webapp/app/services/realtime/resolveRealtimeStreamClient.server.ts

@@ -13,8 +13,8 @@ import { getShadowRealtimeClient } from "./shadowRealtimeClientInstance.server";
 
 type RealtimeBackend = "electric" | "native" | "shadow";
 
-// Two gates, both defaulting to the Electric path: the env master switch, then the
-// per-org `realtimeBackend` feature flag (cached so long-polls don't hit the DB per request).
+// Two gates: the env master switch, then the per-org `realtimeBackend` feature flag (cached so
+// long-polls don't hit the DB per request), falling back to REALTIME_BACKEND_DEFAULT.
 const nativeBackendEnabled = env.REALTIME_BACKEND_NATIVE_ENABLED === "1";
 
 const flag = singleton("realtimeBackendFlag", () => makeFlag($replica));
@@ -61,7 +61,7 @@ async function getRealtimeBackend(
     return cached;
   }
 
-  let backend: RealtimeBackend = "electric";
+  let backend: RealtimeBackend = env.REALTIME_BACKEND_DEFAULT;
 
   try {
     const overrides =
@@ -76,7 +76,7 @@ async function getRealtimeBackend(
 
     backend = await flag({
       key: FEATURE_FLAG.realtimeBackend,
-      defaultValue: "electric",
+      defaultValue: env.REALTIME_BACKEND_DEFAULT,
       overrides: (overrides as Record<string, unknown>) ?? {},
     });
   } catch (error) {
@@ -85,7 +85,7 @@ async function getRealtimeBackend(
       organizationId,
       error,
     });
-    backend = "electric";
+    backend = env.REALTIME_BACKEND_DEFAULT;
   }
 
   backendCache.set(organizationId, backend);