Component Architecture Blueprint for Scalable UI

1// ❌ Bad: Direct framework dependency2import { useRouter } from "next/navigation"3const router = useRouter()4router.push("/products")56// ✅ Good: SDK abstraction7import { useAppRouter } from "@sdk/router"8const router = useAppRouter()9router.push("/products")

1import { createContext, useContext, useId, useState, type FC, type PropsWithChildren } from 'react';23interface TabsContextValue {4  activeId: string;5  setActiveId: (id: string) => void;6  rootId: string;7}89const TabsContext = createContext<TabsContextValue | null>(null);10const useTabs = (): TabsContextValue => {11  const ctx = useContext(TabsContext);12  if (!ctx) throw new Error('Tabs.* must be rendered inside <Tabs>.');13  return ctx;14};1516interface TabsProps extends PropsWithChildren {17  defaultActiveId: string;18  value?: string;19  onValueChange?: (id: string) => void;20}2122const TabsRoot: FC<TabsProps> = ({ defaultActiveId, value, onValueChange, children }) => {23  const [internal, setInternal] = useState(defaultActiveId);24  const activeId = value ?? internal;25  const setActiveId = (id: string): void => {26    if (value === undefined) setInternal(id);27    onValueChange?.(id);28  };29  return (30    <TabsContext.Provider value={{ activeId, setActiveId, rootId: useId() }}>31      {children}32    </TabsContext.Provider>33  );34};3536const List: FC<PropsWithChildren> = ({ children }) => (37  <div role="tablist">{children}</div>38);3940const Trigger: FC<PropsWithChildren<{ id: string }>> = ({ id, children }) => {41  const { activeId, setActiveId, rootId } = useTabs();42  const selected = activeId === id;43  return (44    <button45      role="tab"46      id={`${rootId}-trigger-${id}`}47      aria-selected={selected}48      aria-controls={`${rootId}-panel-${id}`}49      tabIndex={selected ? 0 : -1}50      onClick={() => setActiveId(id)}51    >52      {children}53    </button>54  );55};5657const Panel: FC<PropsWithChildren<{ id: string }>> = ({ id, children }) => {58  const { activeId, rootId } = useTabs();59  if (activeId !== id) return null;60  return (61    <div62      role="tabpanel"63      id={`${rootId}-panel-${id}`}64      aria-labelledby={`${rootId}-trigger-${id}`}65    >66      {children}67    </div>68  );69};7071export const Tabs = Object.assign(TabsRoot, { List, Trigger, Panel });

1src/sdk/2├── index.ts                     # Re-exports all SDK hooks3├── core/4│   ├── sdk.types.ts             # Combined SDK interface5│   ├── sdk.provider.tsx         # Root provider6│   └── sdk.context.ts           # Shared context utilities7├── analytics/8│   ├── analytics.types.ts       # Interface definition9│   ├── analytics.provider.tsx   # Context provider10│   ├── analytics.hooks.ts       # useAnalytics() hook11│   └── index.ts                 # Public exports12├── experiments/13│   ├── experiments.types.ts14│   ├── experiments.provider.tsx15│   ├── experiments.hooks.ts16│   └── index.ts17├── router/18│   ├── router.types.ts19│   ├── router.provider.tsx20│   ├── router.hooks.ts21│   └── index.ts22├── http/23│   ├── http.types.ts24│   ├── http.provider.tsx25│   ├── http.hooks.ts26│   └── index.ts27├── state/28│   ├── state.types.ts29│   ├── state.provider.tsx30│   ├── state.hooks.ts31│   └── index.ts32└── testing/33    ├── test-sdk.provider.tsx    # Test wrapper34    ├── create-mock-sdk.ts       # Mock factory35    └── index.ts

1// src/sdk/core/sdk.types.ts23export interface SdkServices {4  analytics: AnalyticsSdk5  experiments: ExperimentsSdk6  router: RouterSdk7  http: HttpSdk8  state: StateSdk9}

1// src/sdk/analytics/analytics.types.ts23export interface AnalyticsSdk {4  /**5   * Track a custom event6   */7  track(event: string, properties?: Record<string, unknown>): void89  /**10   * Track a page view11   */12  trackPageView(page: string, properties?: Record<string, unknown>): void1314  /**15   * Track component impression (visibility)16   */17  trackImpression(componentId: string, properties?: Record<string, unknown>): void1819  /**20   * Identify a user for analytics21   */22  identify(userId: string, traits?: Record<string, unknown>): void23}

1// src/sdk/experiments/experiments.types.ts23export interface ExperimentsSdk {4  /**5   * Get the variant for an experiment6   * @returns variant name or null if not enrolled7   */8  getVariant(experimentId: string): string | null910  /**11   * Check if a feature flag is enabled12   */13  isFeatureEnabled(featureFlag: string): boolean1415  /**16   * Track that user was exposed to an experiment17   */18  trackExposure(experimentId: string, variant: string): void19}

1// src/sdk/router/router.types.ts23export interface RouterSdk {4  /**5   * Navigate to a new URL (adds to history)6   */7  push(path: string): void89  /**10   * Replace current URL (no history entry)11   */12  replace(path: string): void1314  /**15   * Go back in history16   */17  back(): void1819  /**20   * Prefetch a route for faster navigation21   */22  prefetch(path: string): void2324  /**25   * Current pathname26   */27  pathname: string2829  /**30   * Current query parameters31   */32  query: Record<string, string | string[]>33}

1// src/sdk/http/http.types.ts23export interface HttpSdk {4  get<T>(url: string, options?: RequestOptions): Promise<T>5  post<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>6  put<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>7  delete<T>(url: string, options?: RequestOptions): Promise<T>8}910export interface RequestOptions {11  headers?: Record<string, string>12  signal?: AbortSignal13  cache?: RequestCache14}

1// src/sdk/state/state.types.ts23export interface StateSdk {4  /**5   * Get current state for a key6   */7  getState<T>(key: string): T | undefined89  /**10   * Set state for a key11   */12  setState<T>(key: string, value: T): void1314  /**15   * Subscribe to state changes16   * @returns unsubscribe function17   */18  subscribe<T>(key: string, callback: (value: T) => void): () => void19}

Show 6 hidden lines78// Key pattern: useSdk hook with runtime validation9export const useSdk = (): SdkServices => {10  const ctx = useContext(SdkContext);11  if (!ctx) {12    throw new Error('useSdk must be used within SdkProvider');13  }14  return ctx;15};Show 4 hidden lines2021// Provider wraps application, injecting services22export const SdkProvider: FC<PropsWithChildren<SdkProviderProps>> = ({23  children,24  services,25}) => (26  <SdkContext.Provider value={services}>27    {children}28  </SdkContext.Provider>29);

1// src/sdk/analytics/analytics.hooks.ts23import { useSdk } from "../core/sdk.provider"4import type { AnalyticsSdk } from "./analytics.types"56export const useAnalytics = (): AnalyticsSdk => {7  const sdk = useSdk()8  return sdk.analytics9}

Show 4 hidden lines56export const useExperiment = (experimentId: string): string | null => {7  const { experiments } = useSdk()8  const variant = experiments.getVariant(experimentId)910  useEffect(() => {11    if (variant !== null) {12      experiments.trackExposure(experimentId, variant)13    }14  }, [experimentId, variant, experiments])1516  return variant17}1819export const useFeatureFlag = (flagName: string): boolean => {20  const { experiments } = useSdk()21  return experiments.isFeatureEnabled(flagName)22}

Show 8 hidden lines9/**10 * Creates SDK service implementations using framework-specific APIs.11 * This is the ONLY place where framework imports are allowed.12 */13const createSdkServices = (): SdkServices => ({14  analytics: {Show 28 hidden lines43    },44  },4546  // Key pattern: Router abstraction hides Next.js/Remix differences47  router: {48    push: (path) => window.location.href = path, // Simplified; use framework router49    replace: (path) => window.location.replace(path),50    back: () => window.history.back(),51    prefetch: (path) => { /* Framework-specific prefetch */ },52    pathname: typeof window !== 'undefined' ? window.location.pathname : '/',Show 28 hidden lines81      return res.json();82    },83  },8485  state: createStateAdapter(), // Implement against your state library (Zustand, Jotai, Redux, …)86});8788// Application root wires up concrete implementations89export const AppProviders: FC<PropsWithChildren> = ({ children }) => {90  const services = useMemo(() => createSdkServices(), []);9192  return (93    <SdkProvider services={services}>94      {children}95    </SdkProvider>96  );97};

1src/2├── sdk/                                    # Internal SDKs3│   ├── index.ts                            # Public barrel: all SDK hooks4│   ├── core/5│   │   ├── sdk.types.ts6│   │   ├── sdk.provider.tsx7│   │   └── index.ts8│   ├── analytics/9│   │   ├── analytics.types.ts10│   │   ├── analytics.provider.tsx11│   │   ├── analytics.hooks.ts12│   │   └── index.ts13│   ├── experiments/14│   │   ├── experiments.types.ts15│   │   ├── experiments.provider.tsx16│   │   ├── experiments.hooks.ts17│   │   └── index.ts18│   ├── router/19│   │   ├── router.types.ts20│   │   ├── router.provider.tsx21│   │   ├── router.hooks.ts22│   │   └── index.ts23│   ├── http/24│   │   ├── http.types.ts25│   │   ├── http.provider.tsx26│   │   ├── http.hooks.ts27│   │   └── index.ts28│   ├── state/29│   │   ├── state.types.ts30│   │   ├── state.provider.tsx31│   │   ├── state.hooks.ts32│   │   └── index.ts33│   └── testing/34│       ├── test-sdk.provider.tsx35│       ├── create-mock-sdk.ts36│       └── index.ts37│38├── blocks/                                 # Business-aware building blocks39│   ├── index.ts                            # Public barrel40│   ├── blocks.types.ts                     # Shared Block types41│   │42│   ├── providers/                          # Block-level providers (if needed)43│   │   ├── blocks.provider.tsx44│   │   └── index.ts45│   │46│   ├── testing/                            # Block test utilities47│   │   ├── test-blocks.provider.tsx48│   │   ├── render-block.tsx49│   │   └── index.ts50│   │51│   ├── product-card/52│   │   ├── product-card.component.tsx      # Container53│   │   ├── product-card.view.tsx           # Pure render54│   │   ├── product-card.hooks.ts           # Side effects55│   │   ├── product-card.types.ts           # Types56│   │   ├── product-card.test.tsx           # Tests57│   │   └── index.ts                        # Public API58│   │59│   ├── add-to-cart-button/60│   │   ├── add-to-cart-button.component.tsx61│   │   ├── add-to-cart-button.view.tsx62│   │   ├── add-to-cart-button.hooks.ts63│   │   ├── add-to-cart-button.types.ts64│   │   ├── add-to-cart-button.test.tsx65│   │   └── index.ts66│   │67│   └── [other-blocks]/68│69├── widgets/                                # BFF-driven widgets70│   ├── index.ts                            # Public barrel71│   │72│   ├── types/                              # Shared widget types73│   │   ├── widget.types.ts74│   │   ├── payload.types.ts75│   │   └── index.ts76│   │77│   ├── hero-banner/78│   │   ├── hero-banner.widget.tsx          # Widget container79│   │   ├── hero-banner.view.tsx            # Pure render80│   │   ├── hero-banner.hooks.ts            # Widget logic81│   │   ├── hero-banner.types.ts            # Payload types82│   │   ├── hero-banner.test.tsx83│   │   └── index.ts84│   │85│   ├── product-carousel/86│   │   ├── product-carousel.widget.tsx87│   │   ├── product-carousel.view.tsx88│   │   ├── product-carousel.hooks.ts89│   │   ├── product-carousel.types.ts90│   │   └── index.ts91│   │92│   └── [other-widgets]/93│94├── registries/                             # Page-specific widget registries95│   ├── index.ts96│   ├── registry.types.ts                   # Registry type definitions97│   ├── home.registry.ts                    # Home page widgets98│   ├── pdp.registry.ts                     # Product detail page widgets99│   ├── plp.registry.ts                     # Product listing page widgets100│   ├── cart.registry.ts                    # Cart page widgets101│   └── checkout.registry.ts                # Checkout page widgets102│103├── layout-engine/                          # BFF layout composition104│   ├── index.ts105│   ├── layout-renderer.component.tsx106│   ├── widget-renderer.component.tsx107│   ├── layout.types.ts108│   └── layout.hooks.ts109│110└── shared/                                 # Non-UI utilities111    ├── types/112    │   └── common.types.ts113    └── utils/114        ├── format.utils.ts115        └── validation.utils.ts

Show 3 hidden lines45/**6 * A Block component - business-aware building block7 */8export type BlockComponent<TProps = object> = FC<TProps>910/**11 * A Block View - pure presentational, no side effects12 */13export type BlockView<TProps = object> = FC<TProps>1415/**16 * Block with children17 */18export type BlockWithChildren<TProps = object> = FC<PropsWithChildren<TProps>>1920/**21 * Standard hook result for data-fetching blocks22 */23export interface BlockHookResult<TData, TActions = object> {24  data: TData | null25  isLoading: boolean26  error: Error | null27  actions: TActions28}2930/**31 * Props for analytics tracking (optional on all blocks)32 */33export interface TrackingProps {34  /** Unique identifier for analytics */35  trackingId?: string36  /** Additional tracking data */37  trackingData?: Record<string, unknown>38}

Show 3 hidden lines45/**6 * Base BFF widget payload structure7 */8export interface WidgetPayload<TData = unknown> {9  /** Unique widget instance ID */10  id: string11  /** Widget type identifier (matches registry key) */12  type: string13  /** Widget-specific data from BFF */14  data: TData15  /** Optional pagination info */16  pagination?: WidgetPagination17}1819export interface WidgetPagination {20  cursor: string | null21  hasMore: boolean22  pageSize: number23}2425/**26 * Widget component type27 */28export type WidgetComponent<TData = unknown> = ComponentType<{29  payload: WidgetPayload<TData>30}>3132/**33 * Widget view - pure render layer34 */35export type WidgetView<TProps = object> = ComponentType<TProps>3637/**38 * Widget hook result with pagination support39 */40export interface WidgetHookResult<TData> {41  data: TData | null42  isLoading: boolean43  error: Error | null44  pagination: {45    loadMore: () => Promise<void>46    hasMore: boolean47    isLoadingMore: boolean48  } | null49}

Show 4 hidden lines56/**7 * Configuration for a registered widget8 */9export interface WidgetConfig {10  /** The widget component to render */11  component: ComponentType<{ payload: WidgetPayload }>1213  /** Optional custom error boundary */14  errorBoundary?: ComponentType<{15    children: ReactNode16    fallback?: ReactNode17    onError?: (error: Error) => void18  }>1920  /** Optional suspense fallback (loading state) */21  suspenseFallback?: ReactNode2223  /** Optional skeleton component for loading */24  skeleton?: ComponentType2526  /** Whether to wrap in error boundary (default: true) */27  withErrorBoundary?: boolean2829  /** Whether to wrap in suspense (default: true) */30  withSuspense?: boolean31}3233/**34 * Widget registry - maps widget type IDs to configurations35 */36export type WidgetRegistry = Record<string, WidgetConfig>

1// src/blocks/add-to-cart-button/index.ts23export { AddToCartButton } from "./add-to-cart-button.component"4export { AddToCartButtonView } from "./add-to-cart-button.view"5export { useAddToCart } from "./add-to-cart-button.hooks"6export type { AddToCartButtonProps, AddToCartViewProps } from "./add-to-cart-button.types"