System Design: Design Instagram — Frontend Architecture That Handles 2 Billion Users

App
├── Shell (Navigation + Bottom Tab Bar)
│   ├── HeaderBar (Logo, Notifications, DMs badge)
│   └── BottomNav (Home, Search, Create, Reels, Profile)
├── FeedPage
│   ├── StoryTray
│   │   ├── StoryAvatar (ring animation, seen/unseen state)
│   │   └── StoryViewer (fullscreen overlay)
│   │       ├── StorySlide (image/video + interactive stickers)
│   │       ├── StoryProgress (segmented progress bars)
│   │       └── StoryReplyInput
│   ├── FeedList (virtualized infinite scroll)
│   │   └── FeedPost
│   │       ├── PostHeader (avatar, username, follow button, menu)
│   │       ├── PostMedia
│   │       │   ├── SingleImage (progressive JPEG, blur-up)
│   │       │   ├── Carousel (swipeable, dot indicators)
│   │       │   └── VideoPlayer (autoplay on viewport, muted)
│   │       ├── PostActions (like, comment, share, save)
│   │       ├── LikeCount (real-time, abbreviated)
│   │       ├── PostCaption (expandable, hashtag links)
│   │       └── CommentPreview (top 2 comments, "View all" link)
│   └── NewPostsBanner ("New posts available" sticky banner)
├── PostComposer
│   ├── MediaPicker (grid of camera roll)
│   ├── FilterEditor (CSS filter pipeline)
│   ├── CaptionEditor (mentions, hashtags autocomplete)
│   └── LocationPicker
└── Shared
    ├── DoubleTapLike (heart animation overlay)
    ├── UserAvatar (with story ring indicator)
    ├── SkeletonPost (placeholder matching exact post dimensions)
    └── OfflineIndicator

// Variable-height virtualization with cached measurements
interface PostMeasurement {
  id: string;
  height: number;
  estimatedHeight: number;
  measured: boolean;
}

class FeedVirtualizer {
  private measurements = new Map<string, PostMeasurement>();
  private resizeObserver: ResizeObserver;
  
  constructor() {
    this.resizeObserver = new ResizeObserver((entries) => {
      for (const entry of entries) {
        const postId = entry.target.getAttribute('data-post-id');
        if (postId) {
          this.measurements.set(postId, {
            id: postId,
            height: entry.contentRect.height,
            estimatedHeight: entry.contentRect.height,
            measured: true
          });
        }
      }
      // Batch recalculate offsets
      requestAnimationFrame(() => this.recalculateOffsets());
    });
  }

  getEstimatedHeight(post: Post): number {
    const cached = this.measurements.get(post.id);
    if (cached?.measured) return cached.height;
    
    // Smart estimation based on content type
    const BASE_HEIGHT = 56 + 44 + 60; // header + actions + caption
    switch (post.mediaType) {
      case 'image':
        return BASE_HEIGHT + (post.aspectRatio ? 
          window.innerWidth / post.aspectRatio : 400);
      case 'carousel':
        return BASE_HEIGHT + (post.aspectRatio ? 
          window.innerWidth / post.aspectRatio : 400) + 24; // dots
      case 'video':
        return BASE_HEIGHT + (post.aspectRatio ? 
          window.innerWidth / post.aspectRatio : 500);
      default:
        return BASE_HEIGHT + 400;
    }
  }
}

// Story viewer as a finite state machine
type StoryState = 
  | { type: 'IDLE' }
  | { type: 'VIEWING'; userId: string; slideIndex: number }
  | { type: 'PAUSED'; userId: string; slideIndex: number; pauseReason: 'long_press' | 'video_loading' | 'reply_open' }
  | { type: 'TRANSITIONING'; from: string; to: string }
  | { type: 'REPLY_OPEN'; userId: string; slideIndex: number };

type StoryAction = 
  | { type: 'TAP_RIGHT' }
  | { type: 'TAP_LEFT' }
  | { type: 'LONG_PRESS_START' }
  | { type: 'LONG_PRESS_END' }
  | { type: 'SWIPE_NEXT_USER' }
  | { type: 'SWIPE_PREV_USER' }
  | { type: 'VIDEO_BUFFERING' }
  | { type: 'VIDEO_READY' }
  | { type: 'TIMER_COMPLETE' }
  | { type: 'OPEN_REPLY' }
  | { type: 'CLOSE_REPLY' }
  | { type: 'CLOSE' };

function storyReducer(state: StoryState, action: StoryAction): StoryState {
  switch (state.type) {
    case 'VIEWING':
      switch (action.type) {
        case 'TAP_RIGHT':
          // If last slide of this user, go to next user
          if (isLastSlide(state)) {
            return { type: 'TRANSITIONING', from: state.userId, to: getNextUserId(state.userId) };
          }
          return { ...state, slideIndex: state.slideIndex + 1 };
        
        case 'LONG_PRESS_START':
          return { type: 'PAUSED', ...state, pauseReason: 'long_press' };
        
        case 'VIDEO_BUFFERING':
          return { type: 'PAUSED', ...state, pauseReason: 'video_loading' };
        
        case 'TIMER_COMPLETE':
          // Auto-advance to next slide
          return storyReducer(state, { type: 'TAP_RIGHT' });
        
        case 'OPEN_REPLY':
          return { type: 'REPLY_OPEN', userId: state.userId, slideIndex: state.slideIndex };
        
        default:
          return state;
      }
    
    case 'PAUSED':
      switch (action.type) {
        case 'LONG_PRESS_END':
          if (state.pauseReason === 'long_press') {
            return { type: 'VIEWING', userId: state.userId, slideIndex: state.slideIndex };
          }
          return state;
        
        case 'VIDEO_READY':
          if (state.pauseReason === 'video_loading') {
            return { type: 'VIEWING', userId: state.userId, slideIndex: state.slideIndex };
          }
          return state;
        
        default:
          return state;
      }
    
    default:
      return state;
  }
}

// Progressive image loading pipeline
class ImagePipeline {
  private loadQueue: PriorityQueue<ImageLoadTask>;
  private maxConcurrent = 4; // Browser connection limit per domain
  private activeLoads = 0;
  
  enqueue(task: ImageLoadTask) {
    // Priority: viewport images > 1-ahead > 2-ahead > below fold
    const priority = this.calculatePriority(task);
    this.loadQueue.enqueue(task, priority);
    this.processQueue();
  }

  private calculatePriority(task: ImageLoadTask): number {
    const viewportDistance = task.estimatedOffsetFromViewport;
    if (viewportDistance < 0) return 0; // Already scrolled past, lowest priority
    if (viewportDistance < window.innerHeight) return 100; // In viewport, highest
    if (viewportDistance < window.innerHeight * 2) return 80; // Next screen
    return Math.max(10, 60 - viewportDistance / 100); // Decreasing priority
  }

  async loadImage(task: ImageLoadTask): Promise<void> {
    // Stage 1: Show BlurHash placeholder (instant)
    task.element.style.backgroundImage = decodeBlurHash(task.blurHash);
    
    // Stage 2: Load thumbnail (low-res, ~2KB)
    const thumbnail = await fetch(task.thumbnailUrl);
    task.element.src = URL.createObjectURL(await thumbnail.blob());
    
    // Stage 3: Load full resolution with srcset
    const fullImage = new Image();
    fullImage.srcset = task.srcSet; // e.g., "640w, 1080w, 1440w"
    fullImage.sizes = task.sizes;   // e.g., "(max-width: 768px) 100vw, 614px"
    
    await new Promise((resolve) => {
      fullImage.onload = resolve;
    });
    
    // Crossfade from thumbnail to full
    task.element.style.transition = 'opacity 200ms';
    task.element.src = fullImage.currentSrc;
  }
}

// Normalized store using Zustand
interface InstagramStore {
  // === Normalized entities ===
  posts: Record<string, Post>;
  users: Record<string, User>;
  comments: Record<string, Comment>;
  stories: Record<string, Story>;
  
  // === Feed state ===
  feed: {
    postIds: string[];           // Ordered list of post IDs
    cursor: string | null;       // Pagination cursor
    hasMore: boolean;
    isLoading: boolean;
    isRefreshing: boolean;
    newPostsAvailable: boolean;  // "New posts" banner
  };
  
  // === Story tray state ===
  storyTray: {
    userIds: string[];           // Users with active stories
    viewedUserIds: Set<string>; // Users whose stories we've seen
  };
  
  // === Optimistic mutations queue ===
  pendingMutations: PendingMutation[];
  
  // === Offline cache ===
  lastSyncTimestamp: number;
  offlineQueue: QueuedAction[];
}

interface Post {
  id: string;
  authorId: string;              // References users map
  mediaItems: MediaItem[];       // Array for carousels
  caption: string;
  hashtags: string[];
  location: Location | null;
  likeCount: number;
  commentCount: number;
  isLikedByMe: boolean;
  isSavedByMe: boolean;
  topCommentIds: string[];       // First 2 comments
  createdAt: string;
  // Media metadata for layout
  aspectRatio: number;           // Critical for virtualization
  blurHash: string;              // For progressive loading
  dominantColor: string;         // Fallback background
}

interface MediaItem {
  id: string;
  type: 'image' | 'video';
  url: string;
  thumbnailUrl: string;
  srcSet: string;                // Responsive image sources
  width: number;
  height: number;
  blurHash: string;
  // Video-specific
  duration?: number;
  hlsUrl?: string;               // Adaptive streaming
  hasAudio?: boolean;
}

interface Story {
  id: string;
  userId: string;
  slides: StorySlide[];
  expiresAt: string;
  seenSlideIndex: number;         // Track last seen slide
}

interface StorySlide {
  id: string;
  type: 'image' | 'video';
  url: string;
  duration: number;               // Seconds to display (images default 5s)
  stickers: Sticker[];            // Interactive elements
  musicTrack?: MusicTrack;
}

// Optimistic mutation for offline support
interface PendingMutation {
  id: string;
  type: 'like' | 'unlike' | 'comment' | 'save' | 'unsave';
  entityId: string;
  payload: unknown;
  timestamp: number;
  status: 'pending' | 'syncing' | 'failed';
  retryCount: number;
}

// GET /api/v1/feed?cursor={cursor}&limit=10
interface FeedResponse {
  posts: PostDTO[];
  users: UserDTO[];           // Denormalized for fewer round-trips
  nextCursor: string | null;
  hasMore: boolean;
  // Server-driven UI hints
  serverTime: string;         // For relative timestamps
  experimentFlags: Record<string, boolean>; // A/B test flags
}

interface PostDTO {
  id: string;
  author_id: string;
  media: {
    type: 'image' | 'carousel' | 'video';
    items: Array<{
      url: string;
      thumbnail_url: string;
      srcset: string;          // "640w, 1080w, 1440w"
      width: number;
      height: number;
      blur_hash: string;
      // Video fields
      hls_url?: string;
      duration_seconds?: number;
    }>;
  };
  caption: string;
  like_count: number;
  comment_count: number;
  viewer_has_liked: boolean;
  viewer_has_saved: boolean;
  top_comments: CommentDTO[];  // Embedded, not separate request
  created_at: string;
  location?: { name: string; lat: number; lng: number };
}

// Like/Unlike with optimistic updates
async function toggleLike(postId: string): Promise<void> {
  const post = store.getState().posts[postId];
  const newLiked = !post.isLikedByMe;
  
  // Step 1: Optimistic update (instant)
  store.setState(state => ({
    posts: {
      ...state.posts,
      [postId]: {
        ...post,
        isLikedByMe: newLiked,
        likeCount: post.likeCount + (newLiked ? 1 : -1)
      }
    }
  }));
  
  // Step 2: Trigger haptic feedback + heart animation
  if (newLiked) {
    triggerHaptic('light');
    showHeartAnimation(postId);
  }
  
  // Step 3: Sync to server (with retry)
  const mutation: PendingMutation = {
    id: crypto.randomUUID(),
    type: newLiked ? 'like' : 'unlike',
    entityId: postId,
    payload: {},
    timestamp: Date.now(),
    status: 'pending',
    retryCount: 0
  };
  
  try {
    await api.post(`/posts/${postId}/${newLiked ? 'like' : 'unlike'}`);
    removePendingMutation(mutation.id);
  } catch (error) {
    if (!navigator.onLine) {
      // Queue for later sync
      addToOfflineQueue(mutation);
    } else {
      // Rollback optimistic update
      store.setState(state => ({
        posts: {
          ...state.posts,
          [postId]: {
            ...post, // Restore original state
          }
        }
      }));
      showError('Failed to update. Please try again.');
    }
  }
}

// Double-tap like handler with gesture detection
function useDoubleTapLike(postId: string) {
  const lastTap = useRef<number>(0);
  const tapTimeout = useRef<NodeJS.Timeout>();
  
  const handleTap = useCallback((e: React.TouchEvent) => {
    const now = Date.now();
    const DOUBLE_TAP_THRESHOLD = 300; // ms
    
    if (now - lastTap.current < DOUBLE_TAP_THRESHOLD) {
      // Double tap detected
      clearTimeout(tapTimeout.current);
      const post = store.getState().posts[postId];
      if (!post.isLikedByMe) {
        toggleLike(postId);
      } else {
        // Already liked — still show heart animation
        showHeartAnimation(postId);
      }
    } else {
      // Single tap — wait to confirm it's not a double tap
      tapTimeout.current = setTimeout(() => {
        // Single tap action (if any)
      }, DOUBLE_TAP_THRESHOLD);
    }
    lastTap.current = now;
  }, [postId]);
  
  return handleTap;
}

// WebSocket protocol for real-time feed updates
interface WSMessage {
  type: 'like_update' | 'comment_update' | 'story_update' | 'new_post' | 'typing_indicator';
  payload: unknown;
}

class FeedWebSocket {
  private ws: WebSocket;
  private reconnectDelay = 1000;
  private maxReconnectDelay = 30000;
  
  connect() {
    this.ws = new WebSocket('wss://api.instagram.com/ws/feed');
    
    this.ws.onmessage = (event) => {
      const message: WSMessage = JSON.parse(event.data);
      
      switch (message.type) {
        case 'like_update':
          // Only update if we don't have a pending local mutation
          const pending = store.getState().pendingMutations
            .find(m => m.entityId === message.payload.postId && m.type === 'like');
          if (!pending) {
            store.setState(state => ({
              posts: {
                ...state.posts,
                [message.payload.postId]: {
                  ...state.posts[message.payload.postId],
                  likeCount: message.payload.newCount
                }
              }
            }));
          }
          break;
        
        case 'new_post':
          // Don't insert directly — show "New posts" banner
          store.setState(state => ({
            feed: { ...state.feed, newPostsAvailable: true }
          }));
          break;
        
        case 'story_update':
          // Add/remove user from story tray
          updateStoryTray(message.payload);
          break;
      }
    };
    
    this.ws.onclose = () => {
      // Exponential backoff reconnect
      setTimeout(() => this.connect(), this.reconnectDelay);
      this.reconnectDelay = Math.min(
        this.reconnectDelay * 2, 
        this.maxReconnectDelay
      );
    };
  }
}

<!-- Not just srcset — art direction for different viewports -->
<picture>
  <!-- Desktop: show wider crop -->
  <source 
    media="(min-width: 1024px)" 
    srcset="/img/post-1080.webp 1080w, /img/post-1440.webp 1440w"
    sizes="614px"
    type="image/webp"
  />
  <!-- Mobile: full-width -->
  <source 
    srcset="/img/post-640.webp 640w, /img/post-1080.webp 1080w"
    sizes="100vw"
    type="image/webp"
  />
  <!-- Fallback -->
  <img 
    src="/img/post-1080.jpg" 
    alt={post.accessibilityText}
    loading="lazy"
    decoding="async"
    style={{ aspectRatio: `${post.width}/${post.height}` }}
  />
</picture>

// Intersection Observer for video autoplay
class VideoPlaybackManager {
  private observer: IntersectionObserver;
  private activeVideo: HTMLVideoElement | null = null;

  constructor() {
    this.observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          const video = entry.target as HTMLVideoElement;
          
          if (entry.isIntersecting && entry.intersectionRatio > 0.5) {
            // More than 50% visible — play
            this.playVideo(video);
          } else if (this.activeVideo === video) {
            // Scrolled away — pause and reset
            video.pause();
            this.activeVideo = null;
          }
        });
      },
      { threshold: [0, 0.5, 1.0] }
    );
  }

  private async playVideo(video: HTMLVideoElement) {
    // Pause any currently playing video (only 1 at a time)
    if (this.activeVideo && this.activeVideo !== video) {
      this.activeVideo.pause();
    }
    
    this.activeVideo = video;
    video.muted = true; // Required for autoplay policy
    
    try {
      await video.play();
    } catch (e) {
      // Autoplay blocked — show play button overlay
      video.setAttribute('data-autoplay-blocked', 'true');
    }
  }
}

// Only load carousel slides that are visible or adjacent
function CarouselMedia({ items, postId }: CarouselProps) {
  const [activeIndex, setActiveIndex] = useState(0);
  
  return (
    <div className="carousel-container overflow-hidden">
      <div 
        className="carousel-track flex transition-transform duration-300"
        style={{ transform: `translateX(-${activeIndex * 100}%)` }}
      >
        {items.map((item, index) => {
          // Only render current, previous, and next slides
          const shouldRender = Math.abs(index - activeIndex) <= 1;
          
          return (
            <div key={item.id} className="carousel-slide flex-shrink-0 w-full">
              {shouldRender ? (
                <ProgressiveImage
                  src={item.url}
                  blurHash={item.blurHash}
                  aspectRatio={item.width / item.height}
                />
              ) : (
                // Placeholder with correct dimensions
                <div style={{ aspectRatio: `${item.width}/${item.height}` }} />
              )}
            </div>
          );
        })}
      </div>
      
      {/* Dot indicators */}
      <div className="flex justify-center gap-1 mt-2">
        {items.map((_, i) => (
          <div 
            key={i}
            className={cn(
              "w-1.5 h-1.5 rounded-full transition-colors",
              i === activeIndex ? "bg-primary" : "bg-muted"
            )}
          />
        ))}
      </div>
    </div>
  );
}

// Skeleton that matches exact post dimensions
function PostSkeleton({ aspectRatio = 1 }: { aspectRatio?: number }) {
  return (
    <div className="animate-pulse">
      {/* Header skeleton — exact height match */}
      <div className="flex items-center gap-3 p-3 h-[56px]">
        <div className="w-8 h-8 rounded-full bg-muted" />
        <div className="flex-1">
          <div className="h-3 w-24 bg-muted rounded" />
          <div className="h-2 w-16 bg-muted rounded mt-1" />
        </div>
      </div>
      
      {/* Image skeleton — matches aspect ratio */}
      <div 
        className="bg-muted w-full" 
        style={{ aspectRatio: `1/${aspectRatio}` }} 
      />
      
      {/* Actions skeleton — exact height match */}
      <div className="p-3 h-[44px] flex gap-4">
        <div className="w-6 h-6 bg-muted rounded" />
        <div className="w-6 h-6 bg-muted rounded" />
        <div className="w-6 h-6 bg-muted rounded" />
      </div>
      
      {/* Caption skeleton */}
      <div className="px-3 pb-3 space-y-1.5">
        <div className="h-3 w-20 bg-muted rounded" />
        <div className="h-3 w-full bg-muted rounded" />
        <div className="h-3 w-2/3 bg-muted rounded" />
      </div>
    </div>
  );
}

// Service worker caching strategy
// sw.ts
const CACHE_NAME = 'instagram-v1';
const FEED_CACHE = 'feed-data-v1';

self.addEventListener('fetch', (event: FetchEvent) => {
  const url = new URL(event.request.url);
  
  if (url.pathname.startsWith('/api/v1/feed')) {
    // Network-first with cache fallback for feed
    event.respondWith(
      fetch(event.request)
        .then(response => {
          const clone = response.clone();
          caches.open(FEED_CACHE).then(cache => cache.put(event.request, clone));
          return response;
        })
        .catch(() => caches.match(event.request))
    );
  } else if (url.pathname.match(/\.(jpg|jpeg|webp|png)$/)) {
    // Cache-first for images (they don't change)
    event.respondWith(
      caches.match(event.request).then(cached => {
        if (cached) return cached;
        return fetch(event.request).then(response => {
          const clone = response.clone();
          caches.open(CACHE_NAME).then(cache => cache.put(event.request, clone));
          return response;
        });
      })
    );
  }
});

// Sync offline interactions when back online
self.addEventListener('sync', (event: SyncEvent) => {
  if (event.tag === 'sync-interactions') {
    event.waitUntil(syncOfflineInteractions());
  }
});

async function syncOfflineInteractions() {
  const db = await openDB('offline-queue');
  const mutations = await db.getAll('pending-mutations');
  
  for (const mutation of mutations) {
    try {
      await fetch(`/api/v1/${mutation.endpoint}`, {
        method: 'POST',
        body: JSON.stringify(mutation.payload)
      });
      await db.delete('pending-mutations', mutation.id);
    } catch (e) {
      // Will retry on next sync event
      break;
    }
  }
}

// Accessible post component
function FeedPost({ post }: { post: Post }) {
  return (
    <article 
      aria-label={`Post by ${post.author.username}`}
      role="article"
    >
      {/* Screen readers need context */}
      <div className="sr-only">
        {post.caption}. 
        {post.likeCount} likes. 
        {post.commentCount} comments.
        Posted {formatRelativeTime(post.createdAt)}.
      </div>
      
      <PostHeader user={post.author} />
      
      {post.mediaItems.map((media, index) => (
        <img
          key={media.id}
          src={media.url}
          // AI-generated alt text from server, with user override
          alt={media.altText || `Photo ${index + 1} by ${post.author.username}`}
          role="img"
        />
      ))}
      
      <PostActions 
        post={post}
        // Announce state changes to screen readers
        onLike={() => {
          toggleLike(post.id);
          announceToScreenReader(
            post.isLikedByMe ? 'Post unliked' : 'Post liked'
          );
        }}
      />
    </article>
  );
}

function announceToScreenReader(message: string) {
  const el = document.getElementById('sr-announcer');
  if (el) {
    el.textContent = message;
  }
}
// In root: <div id="sr-announcer" aria-live="polite" className="sr-only" />

function StoryProgressBar({ 
  slides, 
  activeIndex, 
  isPaused, 
  durations 
}: StoryProgressBarProps) {
  const [progress, setProgress] = useState(0);
  const animationRef = useRef<number>();
  const startTimeRef = useRef<number>();
  const pausedProgressRef = useRef<number>(0);

  useEffect(() => {
    if (isPaused) {
      // Save current progress and cancel animation
      pausedProgressRef.current = progress;
      if (animationRef.current) cancelAnimationFrame(animationRef.current);
      return;
    }

    const duration = durations[activeIndex] * 1000; // ms
    startTimeRef.current = performance.now() - (pausedProgressRef.current * duration);

    function animate(now: number) {
      const elapsed = now - startTimeRef.current!;
      const newProgress = Math.min(elapsed / duration, 1);
      setProgress(newProgress);

      if (newProgress < 1) {
        animationRef.current = requestAnimationFrame(animate);
      } else {
        // Auto-advance
        onSlideComplete();
      }
    }

    animationRef.current = requestAnimationFrame(animate);
    return () => {
      if (animationRef.current) cancelAnimationFrame(animationRef.current);
    };
  }, [activeIndex, isPaused]);

  // Reset progress when slide changes
  useEffect(() => {
    setProgress(0);
    pausedProgressRef.current = 0;
  }, [activeIndex]);

  return (
    <div className="flex gap-0.5 px-2 pt-2" role="progressbar">
      {slides.map((_, index) => (
        <div key={index} className="flex-1 h-0.5 bg-white/30 rounded-full overflow-hidden">
          <div
            className="h-full bg-white rounded-full"
            style={{
              width: index < activeIndex 
                ? '100%'                              // Seen slides: full
                : index === activeIndex 
                  ? `${progress * 100}%`              // Current: animated
                  : '0%',                             // Future: empty
              transition: index < activeIndex ? 'none' : undefined
            }}
          />
        </div>
      ))}
    </div>
  );
}