Frontend System Design (HLD) Framework for Production Projects

/**
 * PRODUCTION FRONTEND ARCHITECTURE BLUEPRINT
 * 
 * 1. MODULE BOUNDARIES:
 *    - Shell / Host: Authentication, Navigation, Dynamic Theming, Notification Toast Hub
 *    - Feature Pods: Independent domain packages (@app/analytics, @app/inventory, @app/checkout)
 *    - Shared UI Core: Headless design system primitives, formatting utilities, API clients
 * 
 * 2. COMPONENT HIERARCHY:
 *    <AppShell>
 *      <GlobalErrorBoundary>
 *        <QueryClientProvider>
 *          <HeaderNavigation />
 *          <Suspense fallback={<PageSkeleton />}>
 *            <FeatureContainer>
 *              <WidgetGrid>
 *                <WidgetBoundary name="ChartWidget">
 *                  <VirtualizedDataGrid />
 *                </WidgetBoundary>
 *              </WidgetGrid>
 *            </FeatureContainer>
 *          </Suspense>
 *        </QueryClientProvider>
 *      </GlobalErrorBoundary>
 *    </AppShell>
 * 
 * 3. STATE TAXONOMY:
 *    - Server Cache: TanStack Query (staleTime: 60s, cacheTime: 5m, retry: 3)
 *    - Navigation State: URL query params (?filter=active&page=2) (Single source of truth)
 *    - Ephemeral UI State: Local useState / useReducer (Modal open, hover tooltip)
 *    - Offline Store: IndexedDB via idb-keyval (Draft form mutations)
 */

import { TaskScheduler } from "./scheduler";

export class ResilientApiClient {
  private inFlightRequests = new Map<string, Promise<any>>();
  private scheduler = new TaskScheduler(6); // Max 6 concurrent HTTP/2 streams

  async request<T>(url: string, options: RequestInit = {}): Promise<T> {
    const method = options.method || "GET";
    const cacheKey = `${method}:${url}:${JSON.stringify(options.body || {})}`;

    // 1. Request Deduplication for concurrent GETs
    if (method === "GET" && this.inFlightRequests.has(cacheKey)) {
      return this.inFlightRequests.get(cacheKey)!;
    }

    const promise = this.scheduler.add(async () => {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s deadline

      try {
        const response = await fetch(url, { ...options, signal: controller.signal });
        clearTimeout(timeoutId);

        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        return await response.json();
      } finally {
        this.inFlightRequests.delete(cacheKey);
      }
    });

    if (method === "GET") {
      this.inFlightRequests.set(cacheKey, promise);
    }

    return promise;
  }
}