Component Architecture Blueprint for Scalable UI

1
export interface SdkServices {
2
  analytics: AnalyticsSdk
3
  experiments: ExperimentsSdk
4
  router: RouterSdk
5
  http: HttpSdk
6
  state: StateSdk
7
}

1
export interface AnalyticsSdk {
2
  /**
3
   * Track a custom event
4
   */
5
  track(event: string, properties?: Record<string, unknown>): void
6

7
  /**
8
   * Track a page view
9
   */
10
  trackPageView(page: string, properties?: Record<string, unknown>): void
11

12
  /**
13
   * Track component impression (visibility)
14
   */
15
  trackImpression(componentId: string, properties?: Record<string, unknown>): void
16

17
  /**
18
   * Identify a user for analytics
19
   */
20
  identify(userId: string, traits?: Record<string, unknown>): void
21
}

1
export interface ExperimentsSdk {
2
  /**
3
   * Get the variant for an experiment
4
   * @returns variant name or null if not enrolled
5
   */
6
  getVariant(experimentId: string): string | null
7

8
  /**
9
   * Check if a feature flag is enabled
10
   */
11
  isFeatureEnabled(featureFlag: string): boolean
12

13
  /**
14
   * Track that user was exposed to an experiment
15
   */
16
  trackExposure(experimentId: string, variant: string): void
17
}

1
export interface RouterSdk {
2
  /**
3
   * Navigate to a new URL (adds to history)
4
   */
5
  push(path: string): void
6

7
  /**
8
   * Replace current URL (no history entry)
9
   */
10
  replace(path: string): void
11

12
  /**
13
   * Go back in history
14
   */
15
  back(): void
16

17
  /**
18
   * Prefetch a route for faster navigation
19
   */
20
  prefetch(path: string): void
21

22
  /**
23
   * Current pathname
24
   */
25
  pathname: string
26

27
  /**
28
   * Current query parameters
29
   */
30
  query: Record<string, string | string[]>
31
}

1
export interface HttpSdk {
2
  get<T>(url: string, options?: RequestOptions): Promise<T>
3
  post<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>
4
  put<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>
5
  delete<T>(url: string, options?: RequestOptions): Promise<T>
6
}
7

8
export interface RequestOptions {
9
  headers?: Record<string, string>
10
  signal?: AbortSignal
11
  cache?: RequestCache
12
}

1
export interface StateSdk {
2
  /**
3
   * Get current state for a key
4
   */
5
  getState<T>(key: string): T | undefined
6

7
  /**
8
   * Set state for a key
9
   */
10
  setState<T>(key: string, value: T): void
11

12
  /**
13
   * Subscribe to state changes
14
   * @returns unsubscribe function
15
   */
16
  subscribe<T>(key: string, callback: (value: T) => void): () => void
17
}

6 collapsed lines
1
// src/sdk/core/sdk.provider.tsx
2

3
import { createContext, useContext, type FC, type PropsWithChildren } from 'react';
4
import type { SdkServices } from './sdk.types';
5

6
const SdkContext = createContext<SdkServices | null>(null);
7

8
// Key pattern: useSdk hook with runtime validation
9
export 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
};
4 collapsed lines
16

17
export interface SdkProviderProps {
18
  services: SdkServices;
19
}
20

21
// Provider wraps application, injecting services
22
export const SdkProvider: FC<PropsWithChildren<SdkProviderProps>> = ({
23
  children,
24
  services,
25
}) => (
26
  <SdkContext.Provider value={services}>
27
    {children}
28
  </SdkContext.Provider>
29
);

1
import { useSdk } from "../core/sdk.provider"
2
import type { AnalyticsSdk } from "./analytics.types"
3

4
export const useAnalytics = (): AnalyticsSdk => {
5
  const sdk = useSdk()
6
  return sdk.analytics
7
}

4 collapsed lines
1
// src/sdk/experiments/experiments.hooks.ts
2

3
import { useEffect } from "react"
4
import { useSdk } from "../core/sdk.provider"
5

6
export const useExperiment = (experimentId: string): string | null => {
7
  const { experiments } = useSdk()
8
  const variant = experiments.getVariant(experimentId)
9

10
  useEffect(() => {
11
    if (variant !== null) {
12
      experiments.trackExposure(experimentId, variant)
13
    }
14
  }, [experimentId, variant, experiments])
15

16
  return variant
17
}
18

19
export const useFeatureFlag = (flagName: string): boolean => {
20
  const { experiments } = useSdk()
21
  return experiments.isFeatureEnabled(flagName)
22
}

8 collapsed lines
1
// app/providers.tsx (framework-specific, outside src/)
2

3
'use client'; // Next.js specific
4

5
import { useMemo, type FC, type PropsWithChildren } from 'react';
6
import { useRouter, usePathname, useSearchParams } from 'next/navigation'; // Framework import OK here
7
import { SdkProvider, type SdkServices } from '@sdk/core';
8

9
/**
10
 * Creates SDK service implementations using framework-specific APIs.
11
 * This is the ONLY place where framework imports are allowed.
12
 */
13
const createSdkServices = (): SdkServices => ({
14
  analytics: {
28 collapsed lines
15
    track: (event, props) => {
16
      // Integrate with your analytics provider
17
      // e.g., segment.track(event, props)
18
      console.log('[Analytics] Track:', event, props);
19
    },
20
    trackPageView: (page, props) => {
21
      console.log('[Analytics] Page View:', page, props);
22
    },
23
    trackImpression: (id, props) => {
24
      console.log('[Analytics] Impression:', id, props);
25
    },
26
    identify: (userId, traits) => {
27
      console.log('[Analytics] Identify:', userId, traits);
28
    },
29
  },
30

31
  experiments: {
32
    getVariant: (experimentId) => {
33
      // Integrate with your experimentation platform
34
      // e.g., return optimizely.getVariant(experimentId);
35
      return null;
36
    },
37
    isFeatureEnabled: (flag) => {
38
      // e.g., return launchDarkly.isEnabled(flag);
39
      return false;
40
    },
41
    trackExposure: (experimentId, variant) => {
42
      console.log('[Experiments] Exposure:', experimentId, variant);
43
    },
44
  },
45

46
  // Key pattern: Router abstraction hides Next.js/Remix differences
47
  router: {
48
    push: (path) => window.location.href = path, // Simplified; use framework router
49
    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 : '/',
28 collapsed lines
53
    query: {},
54
  },
55

56
  http: {
57
    get: async (url, opts) => {
58
      const res = await fetch(url, { ...opts, method: 'GET' });
59
      return res.json();
60
    },
61
    post: async (url, body, opts) => {
62
      const res = await fetch(url, {
63
        ...opts,
64
        method: 'POST',
65
        headers: { 'Content-Type': 'application/json', ...opts?.headers },
66
        body: JSON.stringify(body),
67
      });
68
      return res.json();
69
    },
70
    put: async (url, body, opts) => {
71
      const res = await fetch(url, {
72
        ...opts,
73
        method: 'PUT',
74
        headers: { 'Content-Type': 'application/json', ...opts?.headers },
75
        body: JSON.stringify(body),
76
      });
77
      return res.json();
78
    },
79
    delete: async (url, opts) => {
80
      const res = await fetch(url, { ...opts, method: 'DELETE' });
81
      return res.json();
82
    },
83
  },
84

85
  state: createStateAdapter(), // Implement based on your state management choice
86
});
87

88
// Application root wires up concrete implementations
89
export const AppProviders: FC<PropsWithChildren> = ({ children }) => {
90
  const services = useMemo(() => createSdkServices(), []);
91

92
  return (
93
    <SdkProvider services={services}>
94
      {children}
95
    </SdkProvider>
96
  );
97
};

3 collapsed lines
1
// src/blocks/blocks.types.ts
2

3
import type { FC, PropsWithChildren } from "react"
4

5
/**
6
 * A Block component - business-aware building block
7
 */
8
export type BlockComponent<TProps = object> = FC<TProps>
9

10
/**
11
 * A Block View - pure presentational, no side effects
12
 */
13
export type BlockView<TProps = object> = FC<TProps>
14

15
/**
16
 * Block with children
17
 */
18
export type BlockWithChildren<TProps = object> = FC<PropsWithChildren<TProps>>
19

20
/**
21
 * Standard hook result for data-fetching blocks
22
 */
23
export interface BlockHookResult<TData, TActions = object> {
24
  data: TData | null
25
  isLoading: boolean
26
  error: Error | null
27
  actions: TActions
28
}
29

30
/**
31
 * Props for analytics tracking (optional on all blocks)
32
 */
33
export interface TrackingProps {
34
  /** Unique identifier for analytics */
35
  trackingId?: string
36
  /** Additional tracking data */
37
  trackingData?: Record<string, unknown>
38
}

3 collapsed lines
1
// src/widgets/types/widget.types.ts
2

3
import type { ComponentType, ReactNode } from "react"
4

5
/**
6
 * Base BFF widget payload structure
7
 */
8
export interface WidgetPayload<TData = unknown> {
9
  /** Unique widget instance ID */
10
  id: string
11
  /** Widget type identifier (matches registry key) */
12
  type: string
13
  /** Widget-specific data from BFF */
14
  data: TData
15
  /** Optional pagination info */
16
  pagination?: WidgetPagination
17
}
18

19
export interface WidgetPagination {
20
  cursor: string | null
21
  hasMore: boolean
22
  pageSize: number
23
}
24

25
/**
26
 * Widget component type
27
 */
28
export type WidgetComponent<TData = unknown> = ComponentType<{
29
  payload: WidgetPayload<TData>
30
}>
31

32
/**
33
 * Widget view - pure render layer
34
 */
35
export type WidgetView<TProps = object> = ComponentType<TProps>
36

37
/**
38
 * Widget hook result with pagination support
39
 */
40
export interface WidgetHookResult<TData> {
41
  data: TData | null
42
  isLoading: boolean
43
  error: Error | null
44
  pagination: {
45
    loadMore: () => Promise<void>
46
    hasMore: boolean
47
    isLoadingMore: boolean
48
  } | null
49
}

4 collapsed lines
1
// src/registries/registry.types.ts
2

3
import type { ComponentType, ReactNode } from "react"
4
import type { WidgetPayload } from "@widgets/types"
5

6
/**
7
 * Configuration for a registered widget
8
 */
9
export interface WidgetConfig {
10
  /** The widget component to render */
11
  component: ComponentType<{ payload: WidgetPayload }>
12

13
  /** Optional custom error boundary */
14
  errorBoundary?: ComponentType<{
15
    children: ReactNode
16
    fallback?: ReactNode
17
    onError?: (error: Error) => void
18
  }>
19

20
  /** Optional suspense fallback (loading state) */
21
  suspenseFallback?: ReactNode
22

23
  /** Optional skeleton component for loading */
24
  skeleton?: ComponentType
25

26
  /** Whether to wrap in error boundary (default: true) */
27
  withErrorBoundary?: boolean
28

29
  /** Whether to wrap in suspense (default: true) */
30
  withSuspense?: boolean
31
}
32

33
/**
34
 * Widget registry - maps widget type IDs to configurations
35
 */
36
export type WidgetRegistry = Record<string, WidgetConfig>

3 collapsed lines
1
// src/blocks/add-to-cart-button/add-to-cart-button.types.ts
2

3
import type { TrackingProps, BlockHookResult } from "../blocks.types"
4

5
export interface AddToCartButtonProps extends TrackingProps {
6
  sku: string
7
  quantity?: number
8
  variant?: "primary" | "secondary" | "ghost"
9
  size?: "sm" | "md" | "lg"
10
  disabled?: boolean
11
  onSuccess?: () => void
12
  onError?: (error: Error) => void
13
}
14

15
export interface AddToCartViewProps {
16
  onAdd: () => void
17
  isLoading: boolean
18
  error: string | null
19
  variant: "primary" | "secondary" | "ghost"
20
  size: "sm" | "md" | "lg"
21
  disabled: boolean
22
}
23

24
export interface AddToCartActions {
25
  addToCart: () => Promise<void>
26
  reset: () => void
27
}
28

29
export type UseAddToCartResult = BlockHookResult<{ cartId: string }, AddToCartActions>

5 collapsed lines
1
// src/blocks/add-to-cart-button/add-to-cart-button.hooks.ts
2

3
import { useState, useCallback } from "react"
4
import { useAnalytics, useHttpClient } from "@sdk"
5
import type { UseAddToCartResult } from "./add-to-cart-button.types"
6

7
export const useAddToCart = (
8
  sku: string,
9
  quantity: number = 1,
10
  callbacks?: { onSuccess?: () => void; onError?: (error: Error) => void },
11
): UseAddToCartResult => {
12
  const analytics = useAnalytics()
13
  const http = useHttpClient()
5 collapsed lines
14

15
  const [isLoading, setIsLoading] = useState(false)
16
  const [error, setError] = useState<Error | null>(null)
17
  const [data, setData] = useState<{ cartId: string } | null>(null)
18

19
  // Key pattern: Business logic uses SDK abstractions, not framework APIs
20
  const addToCart = useCallback(async (): Promise<void> => {
21
    setIsLoading(true)
22
    setError(null)
23

24
    try {
25
      const response = await http.post<{ cartId: string }>("/api/cart/add", {
26
        sku,
27
        quantity,
28
      })
29

30
      setData(response)
31
      analytics.track("add_to_cart", { sku, quantity, cartId: response.cartId })
32
      callbacks?.onSuccess?.()
33
    } catch (e) {
34
      const error = e instanceof Error ? e : new Error("Failed to add to cart")
35
      setError(error)
36
      analytics.track("add_to_cart_error", { sku, error: error.message })
37
      callbacks?.onError?.(error)
38
      throw error
39
    } finally {
13 collapsed lines
40
      setIsLoading(false)
41
    }
42
  }, [sku, quantity, http, analytics, callbacks])
43

44
  const reset = useCallback((): void => {
45
    setError(null)
46
    setData(null)
47
  }, [])
48

49
  return {
50
    data,
51
    isLoading,
52
    error,
53
    actions: { addToCart, reset },
54
  }
55
}

5 collapsed lines
1
// src/blocks/add-to-cart-button/add-to-cart-button.view.tsx
2

3
import type { FC } from 'react';
4
import { Button, Spinner, Text, Stack } from '@company-name/design-system';
5
import type { AddToCartViewProps } from './add-to-cart-button.types';
6

7
export const AddToCartButtonView: FC<AddToCartViewProps> = ({
8
  onAdd,
9
  isLoading,
10
  error,
11
  variant,
12
  size,
13
  disabled,
14
}) => (
15
  <Stack gap="xs">
16
    <Button
17
      variant={variant}
18
      size={size}
19
      onClick={onAdd}
20
      disabled={disabled || isLoading}
21
      aria-busy={isLoading}
22
      aria-describedby={error ? 'add-to-cart-error' : undefined}
23
    >
24
      {isLoading ? (
25
        <>
26
          <Spinner size="sm" aria-hidden />
27
          <span>Adding...</span>
28
        </>
29
      ) : (
30
        'Add to Cart'
31
      )}
32
    </Button>
33

34
    {error && (
35
      <Text id="add-to-cart-error" color="error" size="sm" role="alert">
36
        {error}
37
      </Text>
38
    )}
39
  </Stack>
40
);

6 collapsed lines
1
// src/blocks/add-to-cart-button/add-to-cart-button.component.tsx
2

3
import type { FC } from 'react';
4
import { useAddToCart } from './add-to-cart-button.hooks';
5
import { AddToCartButtonView } from './add-to-cart-button.view';
6
import type { AddToCartButtonProps } from './add-to-cart-button.types';
7

8
export const AddToCartButton: FC<AddToCartButtonProps> = ({
9
  sku,
10
  quantity = 1,
11
  variant = 'primary',
12
  size = 'md',
13
  disabled = false,
14
  onSuccess,
15
  onError,
16
}) => {
17
  const { isLoading, error, actions } = useAddToCart(sku, quantity, {
18
    onSuccess,
19
    onError
20
  });
21

22
  return (
23
    <AddToCartButtonView
24
      onAdd={actions.addToCart}
25
      isLoading={isLoading}
26
      error={error?.message ?? null}
27
      variant={variant}
28
      size={size}
29
      disabled={disabled}
30
    />
31
  );
32
};

1
export { AddToCartButton } from "./add-to-cart-button.component"
2
export { AddToCartButtonView } from "./add-to-cart-button.view"
3
export { useAddToCart } from "./add-to-cart-button.hooks"
4
export type { AddToCartButtonProps, AddToCartViewProps } from "./add-to-cart-button.types"

3 collapsed lines
1
// src/widgets/product-carousel/product-carousel.types.ts
2

3
import type { WidgetPayload, WidgetHookResult } from "../types"
4

5
export interface ProductCarouselData {
6
  title: string
7
  subtitle?: string
8
  products: ProductItem[]
9
}
10

11
export interface ProductItem {
12
  id: string
13
  sku: string
14
  name: string
15
  price: number
16
  originalPrice?: number
17
  imageUrl: string
18
  rating?: number
19
  reviewCount?: number
20
}
21

22
export type ProductCarouselPayload = WidgetPayload<ProductCarouselData>
23

24
export interface ProductCarouselViewProps {
25
  title: string
26
  subtitle?: string
27
  products: ProductItem[]
28
  onLoadMore?: () => void
29
  hasMore: boolean
30
  isLoadingMore: boolean
31
}
32

33
export type UseProductCarouselResult = WidgetHookResult<ProductCarouselData>

5 collapsed lines
1
// src/widgets/product-carousel/product-carousel.hooks.ts
2

3
import { useState, useCallback, useEffect } from "react"
4
import { useAnalytics, useHttpClient } from "@sdk"
5
import type { ProductCarouselPayload, UseProductCarouselResult } from "./product-carousel.types"
6

7
export const useProductCarousel = (payload: ProductCarouselPayload): UseProductCarouselResult => {
8
  const analytics = useAnalytics()
9
  const http = useHttpClient()
10

7 collapsed lines
11
  const [data, setData] = useState(payload.data)
12
  const [isLoading, setIsLoading] = useState(false)
13
  const [isLoadingMore, setIsLoadingMore] = useState(false)
14
  const [error, setError] = useState<Error | null>(null)
15
  const [cursor, setCursor] = useState(payload.pagination?.cursor ?? null)
16
  const [hasMore, setHasMore] = useState(payload.pagination?.hasMore ?? false)
17

18
  // Track impression when widget becomes visible
19
  useEffect(() => {
20
    analytics.trackImpression(payload.id, {
21
      widgetType: payload.type,
22
      productCount: data.products.length,
23
    })
24
  }, [payload.id, payload.type, analytics, data.products.length])
25

26
  // Key pattern: Widget handles pagination via SDK http abstraction
27
  const loadMore = useCallback(async (): Promise<void> => {
28
    if (!hasMore || isLoadingMore) return
29

30
    setIsLoadingMore(true)
31

32
    try {
33
      const response = await http.get<{
34
        products: ProductItem[]
35
        cursor: string | null
36
        hasMore: boolean
37
      }>(`/api/widgets/${payload.id}/paginate?cursor=${cursor}`)
38

39
      setData((prev) => ({
40
        ...prev,
41
        products: [...prev.products, ...response.products],
42
      }))
43
      setCursor(response.cursor)
44
      setHasMore(response.hasMore)
45

46
      analytics.track("widget_load_more", {
47
        widgetId: payload.id,
48
        itemsLoaded: response.products.length,
49
      })
50
    } catch (e) {
51
      setError(e instanceof Error ? e : new Error("Failed to load more"))
10 collapsed lines
52
    } finally {
53
      setIsLoadingMore(false)
54
    }
55
  }, [payload.id, cursor, hasMore, isLoadingMore, http, analytics])
56

57
  return {
58
    data,
59
    isLoading,
60
    error,
61
    pagination: payload.pagination ? { loadMore, hasMore, isLoadingMore } : null,
62
  }
63
}

6 collapsed lines
1
// src/widgets/product-carousel/product-carousel.view.tsx
2

3
import type { FC } from 'react';
4
import { Section, Carousel, Button, Skeleton } from '@company-name/design-system';
5
import { ProductCard } from '@blocks/product-card';
6
import type { ProductCarouselViewProps } from './product-carousel.types';
7

8
export const ProductCarouselView: FC<ProductCarouselViewProps> = ({
9
  title,
10
  subtitle,
11
  products,
12
  onLoadMore,
13
  hasMore,
14
  isLoadingMore,
15
}) => (
16
  <Section>
17
    <Section.Header>
18
      <Section.Title>{title}</Section.Title>
19
      {subtitle && <Section.Subtitle>{subtitle}</Section.Subtitle>}
20
    </Section.Header>
21

22
    <Carousel itemsPerView={{ base: 2, md: 3, lg: 4 }}>
23
      {products.map((product) => (
24
        <Carousel.Item key={product.id}>
25
          <ProductCard
26
            productId={product.id}
27
            sku={product.sku}
28
            name={product.name}
29
            price={product.price}
30
            originalPrice={product.originalPrice}
31
            imageUrl={product.imageUrl}
32
            rating={product.rating}
33
            reviewCount={product.reviewCount}
34
          />
35
        </Carousel.Item>
36
      ))}
37

38
      {isLoadingMore && (
39
        <Carousel.Item>
40
          <Skeleton variant="product-card" />
41
        </Carousel.Item>
42
      )}
43
    </Carousel>
44

45
    {hasMore && onLoadMore && (
46
      <Section.Footer>
47
        <Button
48
          variant="ghost"
49
          onClick={onLoadMore}
50
          loading={isLoadingMore}
51
        >
52
          Load More
53
        </Button>
54
      </Section.Footer>
55
    )}
56
  </Section>
57
);