refactor(client): deepen core architecture modules

CONTEXT.md

@@ -12,6 +12,22 @@ _Avoid_: Website, property
 The mutable identity, visibility, tracking, exclusion, and feature settings attached to a Site.
 _Avoid_: Site settings, tracking config
 
+**Organization Access Decision**:
+The operation-specific determination of whether an actor may perform an Organization settings action, preserving active-Organization availability, Organization membership role, global role, and pending or error state.
+_Avoid_: Settings guard, role check
+
+**Experiment Authoring**:
+The ordered operation that resolves or creates an Experiment's assignment Feature Flag and primary Goal, then creates or updates the Experiment and produces its implementation state.
+_Avoid_: Experiment form submission, experiment save flow
+
+**Dashboard Time Preset**:
+A well-known named analytics time range whose selector membership and timezone-specific Time value come from the canonical preset groups.
+_Avoid_: Date shortcut, time option
+
+**Replay Session**:
+The client-owned playback lifecycle for one selected Session Replay, including player readiness, position, playback state, speed, activity periods, and visibility recovery.
+_Avoid_: Replay state, player store
+
 **Site Exclusion Decision**:
 The ordered determination that an ingestion request should not be recorded because it matches a Site Configuration exclusion rule.
 _Avoid_: Filter result, blocked event

client/src/api/admin/endpoints/index.ts

@@ -10,7 +10,7 @@ export {
   fetchSiteIsPublic,
   fetchSiteUsage,
 } from "./sites";
-export type { SiteResponse, GetSitesFromOrgResponse, SiteUsageResponse } from "./sites";
+export type { SiteConfig, SiteResponse, GetSitesFromOrgResponse, SiteUsageResponse } from "./sites";
 
 // Organizations endpoints
 export {

client/src/api/admin/endpoints/sites.ts

@@ -70,6 +70,36 @@ export type GetSitesFromOrgResponse = {
   };
 };
 
+export type SiteConfig = {
+  name?: string;
+  type?: "web" | "mobile" | null;
+  domain?: string;
+  public?: boolean;
+  embedEnabled?: boolean;
+  saltUserIds?: boolean;
+  blockBots?: boolean;
+  firstPartyProxy?: boolean;
+  excludedIPs?: string[];
+  excludedCountries?: string[];
+  excludedPaths?: string[];
+  excludedHostnames?: string[];
+  excludedUserAgents?: string[];
+  excludedASNs?: string[];
+  excludedQueryParams?: string[];
+  sessionReplay?: boolean;
+  webVitals?: boolean;
+  trackErrors?: boolean;
+  trackOutbound?: boolean;
+  trackUrlParams?: boolean;
+  trackInitialPageView?: boolean;
+  trackSpaNavigation?: boolean;
+  trackIp?: boolean;
+  trackButtonClicks?: boolean;
+  trackCopy?: boolean;
+  trackFormInteractions?: boolean;
+  tags?: string[];
+};
+
 export function fetchSitesFromOrg(organizationId: string) {
   return authedFetch<GetSitesFromOrgResponse>(`/organizations/${organizationId}/sites`);
 }
@@ -136,39 +166,7 @@ export function moveSite(siteId: number, organizationId: string) {
   });
 }
 
-// Consolidated function to update any site configuration
-export function updateSiteConfig(
-  siteId: number,
-  config: {
-    name?: string;
-    type?: "web" | "mobile" | null;
-    domain?: string;
-    public?: boolean;
-    embedEnabled?: boolean;
-    saltUserIds?: boolean;
-    blockBots?: boolean;
-    firstPartyProxy?: boolean;
-    excludedIPs?: string[];
-    excludedCountries?: string[];
-    excludedPaths?: string[];
-    excludedHostnames?: string[];
-    excludedUserAgents?: string[];
-    excludedASNs?: string[];
-    excludedQueryParams?: string[];
-    sessionReplay?: boolean;
-    webVitals?: boolean;
-    trackErrors?: boolean;
-    trackOutbound?: boolean;
-    trackUrlParams?: boolean;
-    trackInitialPageView?: boolean;
-    trackSpaNavigation?: boolean;
-    trackIp?: boolean;
-    trackButtonClicks?: boolean;
-    trackCopy?: boolean;
-    trackFormInteractions?: boolean;
-    tags?: string[];
-  }
-) {
+export function updateSiteConfig(siteId: number, config: SiteConfig) {
   return authedFetch(`/sites/${siteId}/config`, undefined, {
     method: "PUT",
     data: config,

client/src/api/admin/hooks/useSiteConfiguration.test.ts

@@ -0,0 +1,27 @@
+import { QueryClient } from "@tanstack/react-query";
+import { describe, expect, it } from "vitest";
+import { refreshSiteConfigurationSummaries } from "./useSiteConfiguration";
+
+describe("refreshSiteConfigurationSummaries", () => {
+  it("invalidates every shared summary of Site Configuration", async () => {
+    const queryClient = new QueryClient();
+    const affectedKeys = [
+      ["get-site", 42],
+      ["get-site", "42"],
+      ["get-sites-from-org", "org-1"],
+      ["admin-organizations", { page: 1 }],
+    ] as const;
+    const unrelatedKey = ["site-has-data", "42"] as const;
+
+    for (const queryKey of [...affectedKeys, unrelatedKey]) {
+      queryClient.setQueryData(queryKey, { cached: true });
+    }
+
+    await refreshSiteConfigurationSummaries(queryClient);
+
+    for (const queryKey of affectedKeys) {
+      expect(queryClient.getQueryState(queryKey)?.isInvalidated, JSON.stringify(queryKey)).toBe(true);
+    }
+    expect(queryClient.getQueryState(unrelatedKey)?.isInvalidated).toBe(false);
+  });
+});

client/src/api/admin/hooks/useSiteConfiguration.ts

@@ -0,0 +1,31 @@
+import { QueryClient, useMutation, useQueryClient } from "@tanstack/react-query";
+import { SiteConfig, updateSiteConfig } from "../endpoints/sites";
+
+export type UpdateSiteConfigurationInput = {
+  siteId: number;
+  config: SiteConfig;
+};
+
+/**
+ * Refresh the shared Site summaries that project Site Configuration. Prefix
+ * matching keeps string- and number-keyed Site queries consistent; dedicated
+ * exclusion queries continue to refresh in their operation-specific hooks.
+ */
+export async function refreshSiteConfigurationSummaries(queryClient: QueryClient) {
+  await Promise.all([
+    queryClient.invalidateQueries({ queryKey: ["get-site"] }),
+    queryClient.invalidateQueries({ queryKey: ["get-sites-from-org"] }),
+    queryClient.invalidateQueries({ queryKey: ["admin-organizations"] }),
+  ]);
+}
+
+export function useUpdateSiteConfiguration() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ siteId, config }: UpdateSiteConfigurationInput) => updateSiteConfig(siteId, config),
+    onSuccess: () => {
+      void refreshSiteConfigurationSummaries(queryClient);
+    },
+  });
+}

client/src/app/[site]/errors/components/EnableErrorTracking.tsx

@@ -4,7 +4,7 @@ import { useExtracted } from "next-intl";
 import { AlertTriangle } from "lucide-react";
 import { useParams } from "next/navigation";
 import { toast } from "@/components/ui/sonner";
-import { updateSiteConfig } from "../../../../api/admin/endpoints";
+import { useUpdateSiteConfiguration } from "../../../../api/admin/hooks/useSiteConfiguration";
 import { useGetSite } from "../../../../api/admin/hooks/useSites";
 import { Alert, AlertDescription, AlertTitle } from "../../../../components/ui/alert";
 import { Button } from "../../../../components/ui/button";
@@ -13,7 +13,8 @@ export function EnableErrorTracking() {
   const t = useExtracted();
   const params = useParams();
   const siteId = Number(params.site);
-  const { data: siteMetadata, refetch } = useGetSite(siteId);
+  const { data: siteMetadata } = useGetSite(siteId);
+  const { mutateAsync: updateSiteConfiguration } = useUpdateSiteConfiguration();
 
   if (siteMetadata?.trackErrors) return null;
 
@@ -27,15 +28,15 @@ export function EnableErrorTracking() {
           </AlertTitle>
           <AlertDescription className="text-sm text-neutral-700/80 dark:text-neutral-300/80">
             <div className="mb-2">
-              {t("Error tracking captures JavaScript errors and exceptions from your application.")} <b>{t("Note:")}</b> {t("Enabling error tracking will increase your event usage.")}
+              {t("Error tracking captures JavaScript errors and exceptions from your application.")} <b>{t("Note:")}</b>{" "}
+              {t("Enabling error tracking will increase your event usage.")}
             </div>
             <Button
               size="sm"
               variant="success"
               onClick={async () => {
-                await updateSiteConfig(siteId, { trackErrors: true });
+                await updateSiteConfiguration({ siteId, config: { trackErrors: true } });
                 toast.success(t("Error tracking enabled"));
-                refetch();
               }}
             >
               {t("Enable")}

client/src/app/[site]/experiments/components/CreateExperimentWizard.tsx

@@ -539,100 +539,14 @@ export function CreateExperimentWizard({
 
   const implementationState = savedImplementationState || (isEditing ? buildImplementationState("updated") : null);
 
-  const submitExperiment = async () => {
+  const authorExperiment = async (mode: ImplementationState["mode"]) => {
     const validationError = validateExperimentConfiguration();
     if (validationError) {
       toast.error(validationError);
       return;
     }
 
-    try {
-      let featureFlagId = Number(form.existingFlagId);
-      let flagKey = selectedFlag?.key || form.flagKey.trim();
-      let variantKeys = selectedFlag ? getVariantKeys(selectedFlag) : form.variants.map(variant => variant.key.trim());
-
-      if (form.assignmentMode === "new") {
-        const variants: FeatureFlagVariant[] = form.variants.map(variant => ({
-          key: variant.key.trim(),
-          name: variant.name.trim() || undefined,
-          rolloutPercentage: Number(variant.rolloutPercentage),
-        }));
-
-        const createdFlag = await createFeatureFlagMutation.mutateAsync({
-          key: form.flagKey.trim(),
-          description: form.flagDescription.trim() || `Assignment flag for ${form.name.trim()}`,
-          enabled: true,
-          runtime: "client",
-          flagType: "multivariate",
-          payload: null,
-          variants: [],
-          rolloutPercentage: 100,
-          rules: [],
-          conditionSets: [
-            {
-              name: "Default",
-              rules: [],
-              variants,
-            },
-          ],
-        });
-
-        featureFlagId = createdFlag.data.flagId;
-        flagKey = createdFlag.data.key;
-        variantKeys = getVariantKeys(createdFlag.data);
-      }
-
-      let primaryGoalId: number | null = form.goalMode === "existing" ? Number(form.existingGoalId) : null;
-      let goalType: AnyGoalType | undefined = selectedGoal?.goalType;
-      let goalLabel = form.goalMode === "none" ? undefined : (goalDisplayPattern(selectedGoal) ?? form.goalName.trim());
-
-      if (form.goalMode === "new") {
-        const createdGoal = await createGoalMutation.mutateAsync({
-          siteId: Number(site),
-          name: form.goalName.trim() || `${form.name.trim()} conversion`,
-          goalType: form.goalType,
-          config:
-            form.goalType === "path" ? { pathPattern: form.pathPattern.trim() } : { eventName: form.eventName.trim() },
-        });
-
-        primaryGoalId = createdGoal.goalId;
-        goalType = form.goalType;
-        goalLabel = form.goalType === "path" ? form.pathPattern.trim() : form.eventName.trim();
-      }
-
-      const createdExperiment = await createExperimentMutation.mutateAsync({
-        name: form.name.trim(),
-        description: form.description.trim() || null,
-        hypothesis: form.hypothesis.trim() || null,
-        featureFlagId,
-        primaryGoalId,
-        status: "draft",
-      });
-
-      setSavedImplementationState({
-        mode: "created",
-        experiment: createdExperiment.data,
-        flagKey,
-        variants: variantKeys,
-        goalMode: form.goalMode,
-        goalType,
-        goalLabel,
-      });
-      setStep("implementation");
-      toast.success(t("Experiment created"));
-    } catch (error) {
-      toast.error(error instanceof Error ? error.message : t("Failed to save experiment"));
-    }
-  };
-
-  const saveExperiment = async () => {
-    const validationError = validateExperimentConfiguration();
-    if (validationError) {
-      toast.error(validationError);
-      return;
-    }
-
-    if (!experiment) return;
+    if (mode === "updated" && !experiment) return;
 
     try {
       let featureFlagId = Number(form.existingFlagId);
@@ -688,33 +602,51 @@ export function CreateExperimentWizard({
         goalLabel = form.goalType === "path" ? form.pathPattern.trim() : form.eventName.trim();
       }
 
-      const updatedExperiment = await updateExperimentMutation.mutateAsync({
-        experimentId: experiment.experimentId,
-        payload: {
+      let savedExperiment: Experiment;
+
+      if (mode === "created") {
+        const createdExperiment = await createExperimentMutation.mutateAsync({
           name: form.name.trim(),
           description: form.description.trim() || null,
           hypothesis: form.hypothesis.trim() || null,
           featureFlagId,
           primaryGoalId,
-        },
-      });
+          status: "draft",
+        });
+        savedExperiment = createdExperiment.data;
+      } else {
+        const updatedExperiment = await updateExperimentMutation.mutateAsync({
+          experimentId: experiment!.experimentId,
+          payload: {
+            name: form.name.trim(),
+            description: form.description.trim() || null,
+            hypothesis: form.hypothesis.trim() || null,
+            featureFlagId,
+            primaryGoalId,
+          },
+        });
+        savedExperiment = updatedExperiment.data;
+      }
 
       setSavedImplementationState({
-        mode: "updated",
-        experiment: updatedExperiment.data,
+        mode,
+        experiment: savedExperiment,
         flagKey,
         variants: variantKeys,
         goalMode: form.goalMode,
         goalType,
         goalLabel,
       });
       setStep("implementation");
-      toast.success(t("Experiment updated"));
+      toast.success(mode === "created" ? t("Experiment created") : t("Experiment updated"));
     } catch (error) {
       toast.error(error instanceof Error ? error.message : t("Failed to save experiment"));
     }
   };
 
+  const submitExperiment = () => authorExperiment("created");
+  const saveExperiment = () => authorExperiment("updated");
+
   const renderStep = () => {
     if (step === "basics") {
       return (
@@ -1086,7 +1018,9 @@ window.rybbit.onReady((rybbit) => {
           </p>
         ) : implementationState.goalType && implementationState.goalType !== "event" ? (
           <p className="rounded-md border border-neutral-150 bg-neutral-50 p-3 text-sm text-neutral-600 dark:border-neutral-800 dark:bg-neutral-900/40 dark:text-neutral-300">
-            {t("No conversion event code is needed for this goal. Rybbit tracks it automatically based on user behavior.")}
+            {t(
+              "No conversion event code is needed for this goal. Rybbit tracks it automatically based on user behavior."
+            )}
           </p>
         ) : (
           <p className="rounded-md border border-neutral-150 bg-neutral-50 p-3 text-sm text-neutral-600 dark:border-neutral-800 dark:bg-neutral-900/40 dark:text-neutral-300">