System Design: Design an API Progress Bar — The Illusion of Speed

ProgressBarSystem
├── ProgressBarController (singleton, framework-agnostic)
│   ├── TrickleAlgorithm (simulated progress math)
│   ├── RequestTracker (counts active requests)
│   ├── AnimationScheduler (RAF-based updates)
│   └── StateEmitter (notifies UI of state changes)
├── ProgressBar (React component)
│   ├── BarTrack (full-width container, fixed position)
│   └── BarFill (animated fill with glow effect)
├── Interceptors
│   ├── FetchInterceptor (monkey-patches global fetch)
│   ├── AxiosInterceptor (request/response interceptors)
│   └── RouterInterceptor (React Router navigation events)
└── Accessibility
    ├── AriaProgressBar (hidden element for screen readers)
    └── ScreenReaderAnnouncer ("Loading" / "Loaded" announcements)

class TrickleAlgorithm {
  private progress = 0;
  
  // Get the next increment based on current progress
  // Key insight: increments get SMALLER as progress increases
  getIncrement(): number {
    if (this.progress < 0.2) return 0.1;          // 0-20%: fast
    if (this.progress < 0.5) return 0.04;         // 20-50%: moderate
    if (this.progress < 0.8) return 0.02;         // 50-80%: slow
    if (this.progress < 0.99) return 0.005;       // 80-99%: crawl
    return 0;                                      // 99%+: stop (never reach 100)
  }
  
  // Add randomness for natural feel
  trickle(): number {
    const increment = this.getIncrement();
    // Add +/- 50% randomness
    const jitter = increment * (0.5 + Math.random());
    this.progress = Math.min(0.994, this.progress + jitter);
    return this.progress;
  }
  
  // Force to specific value (for real progress or completion)
  set(value: number) {
    this.progress = Math.max(this.progress, value); // Never go backwards
  }
  
  reset() {
    this.progress = 0;
  }
}

interface ProgressBarState {
  // Core state
  status: "idle" | "loading" | "completing" | "error";
  progress: number;          // 0 to 1
  
  // Request tracking
  activeRequests: number;    // Count of in-flight requests
  totalRequests: number;     // Total requests in this batch
  completedRequests: number; // Completed requests in this batch
  
  // Timing
  startTime: number | null;  // When the bar started
  minDisplayUntil: number | null; // Don’t hide before this time
  
  // Visual
  color: "primary" | "error"; // Bar color
  visible: boolean;          // Whether bar is rendered
  opacity: number;           // For fade animation
}

// State machine transitions
type ProgressAction =
  | { type: "START" }                          // New request started
  | { type: "SET_PROGRESS"; value: number }    // Set specific progress (uploads)
  | { type: "TRICKLE" }                        // Auto-increment progress
  | { type: "COMPLETE_ONE" }                   // One of N requests completed
  | { type: "COMPLETE_ALL" }                   // All requests completed
  | { type: "ERROR" }                          // Request failed
  | { type: "RESET" }                          // Hide and reset
  | { type: "CANCEL" };                        // Request cancelled

function progressReducer(state: ProgressBarState, action: ProgressAction): ProgressBarState {
  switch (action.type) {
    case "START":
      if (state.status === "idle") {
        return {
          ...state,
          status: "loading",
          progress: 0.08 + Math.random() * 0.05, // Start at 8-13%
          activeRequests: 1,
          totalRequests: 1,
          completedRequests: 0,
          startTime: performance.now(),
          minDisplayUntil: performance.now() + 300, // Min 300ms visible
          color: "primary",
          visible: true,
          opacity: 1,
        };
      }
      // Already loading — add to active count
      return {
        ...state,
        activeRequests: state.activeRequests + 1,
        totalRequests: state.totalRequests + 1,
      };
    
    case "TRICKLE":
      if (state.status !== "loading") return state;
      const algo = new TrickleAlgorithm();
      algo.set(state.progress);
      return {
        ...state,
        progress: algo.trickle(),
      };
    
    case "COMPLETE_ONE":
      const newCompleted = state.completedRequests + 1;
      const newActive = state.activeRequests - 1;
      
      if (newActive <= 0) {
        // All requests done
        return progressReducer(
          { ...state, completedRequests: newCompleted, activeRequests: 0 },
          { type: "COMPLETE_ALL" }
        );
      }
      
      // Boost progress based on completion ratio
      const completionRatio = newCompleted / state.totalRequests;
      const boostedProgress = Math.max(
        state.progress,
        completionRatio * 0.9 // Up to 90% based on completed requests
      );
      
      return {
        ...state,
        activeRequests: newActive,
        completedRequests: newCompleted,
        progress: boostedProgress,
      };
    
    case "COMPLETE_ALL":
      return {
        ...state,
        status: "completing",
        progress: 1, // Snap to 100%
      };
    
    case "ERROR":
      return {
        ...state,
        status: "error",
        progress: 1,
        color: "error",
      };
    
    case "RESET":
      return {
        status: "idle",
        progress: 0,
        activeRequests: 0,
        totalRequests: 0,
        completedRequests: 0,
        startTime: null,
        minDisplayUntil: null,
        color: "primary",
        visible: false,
        opacity: 0,
      };
    
    default:
      return state;
  }
}

class ProgressBarController {
  private state: ProgressBarState;
  private trickleInterval: number | null = null;
  private hideTimeout: number | null = null;
  private listeners = new Set<(state: ProgressBarState) => void>();
  
  // === Public API ===
  
  start() {
    this.dispatch({ type: "START" });
    this.startTrickling();
  }
  
  done() {
    this.stopTrickling();
    this.dispatch({ type: "COMPLETE_ONE" });
    
    if (this.state.status === "completing") {
      this.scheduleHide();
    }
  }
  
  error() {
    this.stopTrickling();
    this.dispatch({ type: "ERROR" });
    this.scheduleHide(1000); // Show error state for 1s
  }
  
  set(progress: number) {
    this.dispatch({ type: "SET_PROGRESS", value: progress });
  }
  
  cancel() {
    this.stopTrickling();
    this.dispatch({ type: "RESET" });
  }
  
  // === Internal ===
  
  private startTrickling() {
    if (this.trickleInterval) return;
    
    this.trickleInterval = window.setInterval(() => {
      this.dispatch({ type: "TRICKLE" });
    }, 200 + Math.random() * 300); // Every 200-500ms
  }
  
  private stopTrickling() {
    if (this.trickleInterval) {
      clearInterval(this.trickleInterval);
      this.trickleInterval = null;
    }
  }
  
  private scheduleHide(delay = 400) {
    // Respect minimum display time
    const now = performance.now();
    const minUntil = this.state.minDisplayUntil || 0;
    const actualDelay = Math.max(delay, minUntil - now);
    
    this.hideTimeout = window.setTimeout(() => {
      this.dispatch({ type: "RESET" });
    }, actualDelay);
  }
  
  // === Observer pattern ===
  subscribe(listener: (state: ProgressBarState) => void) {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }
  
  private dispatch(action: ProgressAction) {
    this.state = progressReducer(this.state, action);
    this.listeners.forEach(l => l(this.state));
  }
}

// Singleton instance
export const progressBar = new ProgressBarController();

// Automatically track all fetch requests
function installFetchInterceptor(
  controller: ProgressBarController,
  options: {
    exclude?: RegExp[];      // URLs to ignore (e.g., analytics)
    minDuration?: number;    // Don’t show for requests under this ms
  } = {}
) {
  const originalFetch = window.fetch;
  const { exclude = [], minDuration = 150 } = options;
  
  window.fetch = async function(input: RequestInfo | URL, init?: RequestInit) {
    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
    
    // Skip excluded URLs
    if (exclude.some(pattern => pattern.test(url))) {
      return originalFetch(input, init);
    }
    
    // Delay showing the bar for fast requests
    let showTimer: number | null = null;
    let started = false;
    
    showTimer = window.setTimeout(() => {
      controller.start();
      started = true;
    }, minDuration);
    
    try {
      const response = await originalFetch(input, init);
      
      if (showTimer) clearTimeout(showTimer);
      
      if (started) {
        if (response.ok) {
          controller.done();
        } else {
          controller.error();
        }
      }
      
      return response;
    } catch (error) {
      if (showTimer) clearTimeout(showTimer);
      
      if (started) {
        controller.error();
      }
      
      throw error;
    }
  };
  
  // Return cleanup function
  return () => {
    window.fetch = originalFetch;
  };
}

// The React component — pure presentation
function ProgressBar() {
  const [state, setState] = useState<ProgressBarState>(progressBar.getState());
  
  useEffect(() => {
    return progressBar.subscribe(setState);
  }, []);
  
  if (!state.visible) return null;
  
  return (
    <div
      className="fixed top-0 left-0 right-0 z-[9999] h-[3px] pointer-events-none"
      role="progressbar"
      aria-valuenow={Math.round(state.progress * 100)}
      aria-valuemin={0}
      aria-valuemax={100}
      aria-label="Page loading progress"
    >
      <div
        className={cn(
          "h-full transition-opacity duration-300",
          state.color === "error" ? "bg-destructive" : "bg-primary"
        )}
        style={{
          // GPU-composited animation — no layout thrashing
          transform: `scaleX(${state.progress})`,
          transformOrigin: "left",
          transition: state.status === "completing"
            ? "transform 200ms ease-out, opacity 300ms ease 200ms"
            : "transform 400ms cubic-bezier(0.4, 0, 0.2, 1)",
          opacity: state.opacity,
        }}
      />
      {/* Glow effect at the leading edge */}
      {state.status === "loading" && (
        <div
          className="absolute top-0 right-0 h-full w-24"
          style={{
            transform: `translateX(${state.progress * 100}vw)`,
            background: state.color === "error"
              ? "linear-gradient(to right, transparent, hsl(var(--destructive) / 0.4))"
              : "linear-gradient(to right, transparent, hsl(var(--primary) / 0.4))",
            filter: "blur(3px)",
          }}
        />
      )}
    </div>
  );
}

// React Router integration
function useRouterProgress() {
  const navigation = useNavigation(); // React Router v6
  
  useEffect(() => {
    if (navigation.state === "loading") {
      progressBar.start();
    } else {
      progressBar.done();
    }
  }, [navigation.state]);
}

// Problem: A bar that appears for 50ms and disappears is worse than no bar
// Solution: Only show the bar if the request takes longer than a threshold

class SmartProgressBar extends ProgressBarController {
  private showDelay = 150; // ms — don’t show for requests under 150ms
  private showTimer: number | null = null;
  
  start() {
    // Don’t show immediately — wait to see if the request is fast
    this.showTimer = window.setTimeout(() => {
      super.start();
      this.showTimer = null;
    }, this.showDelay);
  }
  
  done() {
    if (this.showTimer) {
      // Request completed before the delay — never show the bar
      clearTimeout(this.showTimer);
      this.showTimer = null;
      return;
    }
    super.done();
  }
}

// Problem: A dashboard page loads 6 API calls simultaneously.
// Without aggregation, the bar would complete/restart 6 times.

class AggregatingProgressBar extends ProgressBarController {
  private requestCounter = 0;
  private completionCounter = 0;
  private batchTimer: number | null = null;
  private BATCH_WINDOW = 50; // ms to group requests into a batch
  
  start() {
    this.requestCounter++;
    
    if (this.requestCounter === 1) {
      // First request — start the bar
      super.start();
      
      // Start a batch window — any requests starting within 50ms
      // are considered part of the same "page load"
      this.batchTimer = window.setTimeout(() => {
        this.batchTimer = null;
      }, this.BATCH_WINDOW);
    }
  }
  
  done() {
    this.completionCounter++;
    
    // Boost progress based on completion ratio
    const ratio = this.completionCounter / this.requestCounter;
    this.set(ratio * 0.9); // Each completion pushes progress forward
    
    if (this.completionCounter >= this.requestCounter) {
      // All requests in this batch are done
      super.done();
      this.requestCounter = 0;
      this.completionCounter = 0;
    }
  }
}

/* Performance-critical CSS */
.progress-bar-track {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: 3px;
  z-index: 9999;
  pointer-events: none; /* Don’t block clicks */
  /* Force GPU layer */
  will-change: transform, opacity;
  contain: strict; /* Full layout isolation */
}

.progress-bar-fill {
  height: 100%;
  transform-origin: left;
  /* Use scaleX instead of width — GPU composited */
  transform: scaleX(var(--progress, 0));
  /* Smooth easing that feels natural */
  transition: transform 400ms cubic-bezier(0.4, 0, 0.2, 1);
}

.progress-bar-fill.completing {
  /* Fast snap to 100% */
  transition: transform 200ms ease-out,
              opacity 300ms ease 200ms; /* Fade after fill */
}

/* The glow pulsation at the tip */
.progress-bar-glow {
  position: absolute;
  right: -8px;
  top: -2px;
  width: 80px;
  height: 7px;
  border-radius: 50%;
  filter: blur(3px);
  animation: pulse 2s ease-in-out infinite;
}

@keyframes pulse {
  0%, 100% { opacity: 0.6; }
  50% { opacity: 1; }
}

// For file uploads, use XMLHttpRequest or fetch with ReadableStream for real progress

async function uploadWithProgress(
  file: File,
  url: string,
  controller: ProgressBarController
): Promise<Response> {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    
    controller.start();
    
    xhr.upload.addEventListener("progress", (e) => {
      if (e.lengthComputable) {
        const progress = e.loaded / e.total;
        controller.set(progress * 0.95); // Reserve 5% for server processing
      }
    });
    
    xhr.addEventListener("load", () => {
      controller.set(1);
      controller.done();
      resolve(new Response(xhr.response, {
        status: xhr.status,
        headers: parseHeaders(xhr.getAllResponseHeaders()),
      }));
    });
    
    xhr.addEventListener("error", () => {
      controller.error();
      reject(new Error("Upload failed"));
    });
    
    xhr.addEventListener("abort", () => {
      controller.cancel();
    });
    
    xhr.open("POST", url);
    const formData = new FormData();
    formData.append("file", file);
    xhr.send(formData);
  });
}

// Modern alternative using fetch + ReadableStream (for download progress)
async function downloadWithProgress(
  url: string,
  controller: ProgressBarController
): Promise<Blob> {
  const response = await fetch(url);
  const contentLength = Number(response.headers.get("content-length")) || 0;
  const reader = response.body!.getReader();
  
  controller.start();
  let received = 0;
  const chunks: Uint8Array[] = [];
  
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    chunks.push(value);
    received += value.length;
    
    if (contentLength > 0) {
      controller.set(received / contentLength);
    }
  }
  
  controller.done();
  return new Blob(chunks);
}

function AccessibleProgressBar({ state }: { state: ProgressBarState }) {
  const announcerRef = useRef<HTMLDivElement>(null);
  const prevStatus = useRef(state.status);
  
  useEffect(() => {
    // Announce state changes to screen readers
    if (prevStatus.current !== state.status) {
      if (state.status === "loading") {
        announce("Loading content");
      } else if (state.status === "completing") {
        announce("Content loaded");
      } else if (state.status === "error") {
        announce("Error loading content");
      }
      prevStatus.current = state.status;
    }
  }, [state.status]);
  
  function announce(message: string) {
    if (announcerRef.current) {
      announcerRef.current.textContent = message;
    }
  }
  
  return (
    <>
      {/* Visual progress bar */}
      <div
        role="progressbar"
        aria-valuenow={Math.round(state.progress * 100)}
        aria-valuemin={0}
        aria-valuemax={100}
        aria-label="Page loading progress"
        aria-hidden={!state.visible}
      >
        {/* ... bar UI ... */}
      </div>
      
      {/* Screen reader announcements */}
      <div
        ref={announcerRef}
        aria-live="assertive"
        aria-atomic="true"
        className="sr-only"
      />
    </>
  );
}

// Edge case 1: Request completes during the hide animation
// The bar is fading out (opacity -> 0) and a new request starts.
// Without handling this, the bar appears at the old progress.
class RobustProgressBar extends ProgressBarController {
  start() {
    // Cancel any pending hide animation
    if (this.hideTimeout) {
      clearTimeout(this.hideTimeout);
      this.hideTimeout = null;
    }
    
    // If bar is visible but completing, reset progress first
    if (this.state.status === "completing" || this.state.status === "error") {
      // Instantly reset (no animation)
      this.dispatch({ type: "RESET" });
      // Then start fresh on next frame
      requestAnimationFrame(() => {
        this.dispatch({ type: "START" });
      });
      return;
    }
    
    super.start();
  }
}

// Edge case 2: Multiple tabs making requests
// Each tab has its own progress bar, but they share session cookies.
// Not a bug, but worth considering if using SharedWorker.

// Edge case 3: Slow-starting request followed by fast request
// Request A starts, bar shows. Request B starts and completes instantly.
// Without aggregation, bar would reset to 0 after B completes,
// even though A is still pending.

// Edge case 4: Browser back/forward navigation
// bfcache (back-forward cache) restores the page instantly,
// but the progress bar might still be in "loading" state from
// when the page was cached. Solution: reset on pageshow event.
window.addEventListener("pageshow", (event) => {
  if (event.persisted) { // Page restored from bfcache
    progressBar.cancel();
  }
});