System Design: Design Facebook.com — A Complete Frontend Architecture Deep Dive

┌─────────────────────────────────────────────────────┐
│                    App Shell                         │
│  ┌──────────┐  ┌──────────────────────┐  ┌────────┐│
│  │  Header   │  │    Main Content      │  │Sidebar ││
│  │  (Nav)    │  │  ┌────────────────┐  │  │(Chat,  ││
│  │           │  │  │  Stories Bar    │  │  │Contacts││
│  └──────────┘  │  └────────────────┘  │  │Trends) ││
│                │  ┌────────────────┐  │  │        ││
│                │  │ Post Composer   │  │  │        ││
│                │  └────────────────┘  │  │        ││
│                │  ┌────────────────┐  │  │        ││
│                │  │   Feed List     │  │  │        ││
│                │  │  ┌────────────┐│  │  │        ││
│                │  │  │ Feed Post  ││  │  │        ││
│                │  │  │  ┌───────┐ ││  │  │        ││
│                │  │  │  │Header ││  │  │        ││
│                │  │  │  │Content││  │  │        ││
│                │  │  │  │Actions││  │  │        ││
│                │  │  │  │Comment││  │  │        ││
│                │  │  │  └───────┘ ││  │  │        ││
│                │  │  └────────────┘│  │  │        ││
│                │  │  ... more posts │  │  └────────┘│
│                │  └────────────────┘  │            │
│                └──────────────────────┘            │
└─────────────────────────────────────────────────────┘

// Traditional SPA approach
function App() {
  return (
    <BrowserRouter>
      <AuthProvider>
        <Route path="/feed" element={<FeedPage />} />
      </AuthProvider>
    </BrowserRouter>
  );
}

// Next.js style SSR
export async function getServerSideProps(context) {
  const { req } = context;
  const token = req.cookies.session;
  const feedData = await fetchFeed(token, { limit: 10 });

  return {
    props: { initialFeed: feedData }
  };
}

function FeedPage({ initialFeed }) {
  const [posts, setPosts] = useState(initialFeed);
  // Hydrate and take over with CSR for subsequent interactions
}

// React 18 streaming with Suspense boundaries
function FeedPage() {
  return (
    <Layout>
      <StoriesBar />           {/* Hydrates immediately */}
      <PostComposer />         {/* Hydrates immediately */}
      <Suspense fallback={<FeedSkeleton />}>
        <FeedList />            {/* Streams in, hydrates when ready */}
      </Suspense>
      <Suspense fallback={<SidebarSkeleton />}>
        <Sidebar />             {/* Lowest priority hydration */}
      </Suspense>
    </Layout>
  );
}

// ===== Core Data Types =====

interface User {
  id: string;
  name: string;
  avatarUrl: string;
  profileUrl: string;
}

interface FeedPost {
  id: string;
  author: User;
  content: PostContent;
  createdAt: string;         // ISO 8601 UTC timestamp
  updatedAt: string;
  audience: 'public' | 'friends' | 'only_me';
  reactions: ReactionSummary;
  commentsCount: number;
  sharesCount: number;
  hasUserReacted: ReactionType | null;
  hasUserBookmarked: boolean;
}

// Polymorphic content — this is KEY
type PostContent =
  | { type: 'text'; body: string }
  | { type: 'image'; body: string; images: MediaItem[] }
  | { type: 'video'; body: string; video: VideoItem }
  | { type: 'link'; body: string; linkPreview: LinkPreview }
  | { type: 'shared_post'; body: string; originalPost: FeedPost };

interface MediaItem {
  id: string;
  url: string;
  thumbnailUrl: string;
  width: number;
  height: number;
  altText: string;
}

interface VideoItem {
  id: string;
  url: string;
  thumbnailUrl: string;
  duration: number;          // seconds
  width: number;
  height: number;
  hlsUrl?: string;           // For adaptive bitrate streaming
}

interface LinkPreview {
  url: string;
  title: string;
  description: string;
  imageUrl: string;
  siteName: string;
  favicon: string;
}

type ReactionType = 'like' | 'love' | 'haha' | 'wow' | 'sad' | 'angry';

interface ReactionSummary {
  total: number;
  topReactions: ReactionType[];  // Top 3 reactions to show icons
  byType: Partial<Record<ReactionType, number>>;
}

interface Comment {
  id: string;
  author: User;
  content: string;
  createdAt: string;
  reactions: ReactionSummary;
  replies: Comment[];        // Nested threading
  repliesCount: number;
  hasUserReacted: ReactionType | null;
}

interface Story {
  id: string;
  author: User;
  mediaUrl: string;
  mediaType: 'image' | 'video';
  createdAt: string;
  expiresAt: string;         // 24 hours from creation
  isViewed: boolean;
}

function PostBody({ content }: { content: PostContent }) {
  switch (content.type) {
    case 'text':
      return <TextPost body={content.body} />;
    case 'image':
      return <ImagePost body={content.body} images={content.images} />;
    case 'video':
      return <VideoPost body={content.body} video={content.video} />;
    case 'link':
      return <LinkPost body={content.body} preview={content.linkPreview} />;
    case 'shared_post':
      return <SharedPost body={content.body} original={content.originalPost} />;
  }
}

function RelativeTime({ timestamp }: { timestamp: string }) {
  const [display, setDisplay] = useState('');

  useEffect(() => {
    const update = () => {
      const seconds = Math.floor(
        (Date.now() - new Date(timestamp).getTime()) / 1000
      );

      const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

      if (seconds < 60) setDisplay(rtf.format(-seconds, 'second'));
      else if (seconds < 3600) setDisplay(rtf.format(-Math.floor(seconds / 60), 'minute'));
      else if (seconds < 86400) setDisplay(rtf.format(-Math.floor(seconds / 3600), 'hour'));
      else setDisplay(rtf.format(-Math.floor(seconds / 86400), 'day'));
    };

    update();
    const interval = setInterval(update, 60000); // Update every minute
    return () => clearInterval(interval);
  }, [timestamp]);

  return <time dateTime={timestamp}>{display}</time>;
}

// Using Zustand for state management
interface FeedStore {
  // Feed data
  posts: Map<string, FeedPost>;     // Normalized by ID for O(1) lookups
  feedOrder: string[];               // Array of post IDs in display order
  cursor: string | null;             // For pagination
  hasMore: boolean;

  // UI state
  isLoadingMore: boolean;
  isRefreshing: boolean;
  newPostsCount: number;             // "3 new posts" banner
  pendingPosts: FeedPost[];          // Optimistic posts awaiting confirmation

  // Actions
  fetchFeed: (cursor?: string) => Promise<void>;
  createPost: (content: PostContent) => Promise<void>;
  reactToPost: (postId: string, reaction: ReactionType) => void;
  deletePost: (postId: string) => void;
  showNewPosts: () => void;
}

// GET /api/v1/feed?cursor={lastPostTimestamp}&limit=10

// Request
interface FetchFeedRequest {
  cursor?: string;   // ISO timestamp of last post seen
  limit?: number;    // Default 10, max 25
}

// Response
interface FetchFeedResponse {
  posts: FeedPost[];
  pagination: {
    nextCursor: string | null;  // null means no more posts
    hasMore: boolean;
  };
  metadata: {
    totalUnread: number;        // For "new posts" banner
    serverTime: string;         // For clock skew correction
  };
}

// POST /api/v1/posts

// Request (multipart/form-data for media)
interface CreatePostRequest {
  content: string;
  contentType: 'text' | 'image' | 'video' | 'link';
  audience: 'public' | 'friends' | 'only_me';
  media?: File[];               // Up to 10 images or 1 video
  linkUrl?: string;             // For link-type posts
}

// Response
interface CreatePostResponse {
  post: FeedPost;               // Full post object with generated ID
  uploadUrls?: string[];        // Pre-signed URLs for media upload
}

// Client uploads media directly in the POST request
const formData = new FormData();
formData.append('content', 'Check out this photo!');
formData.append('media', file);

const response = await fetch('/api/v1/posts', {
  method: 'POST',
  body: formData,
});

// Step 1: Create post, get pre-signed upload URLs
const { post, uploadUrls } = await createPost({ content, contentType: 'image' });

// Step 2: Upload media directly to cloud storage (S3/GCS)
await Promise.all(
  files.map((file, i) =>
    fetch(uploadUrls[i], {
      method: 'PUT',
      body: file,
      headers: { 'Content-Type': file.type },
    })
  )
);

// Step 3: Notify server that upload is complete
await fetch(`/api/v1/posts/${post.id}/media-ready`, { method: 'POST' });

// POST /api/v1/posts/:postId/reactions

interface ReactRequest {
  reactionType: ReactionType;   // 'like' | 'love' | 'haha' | etc.
}

// Response: 200 OK with updated reaction counts
interface ReactResponse {
  reactions: ReactionSummary;
}

// DELETE /api/v1/posts/:postId/reactions
// Removes user's reaction — Response: same as above

// Client-side WebSocket manager
class FeedWebSocketManager {
  private ws: WebSocket | null = null;
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 10;
  private heartbeatInterval: number | null = null;

  connect(token: string) {
    this.ws = new WebSocket(
      `wss://api.facebook.com/ws/feed?token=${token}`
    );

    this.ws.onopen = () => {
      this.reconnectAttempts = 0;
      this.startHeartbeat();
      this.subscribe(['feed_updates', 'reactions', 'typing']);
    };

    this.ws.onmessage = (event) => {
      const message: WSMessage = JSON.parse(event.data);
      this.handleMessage(message);
    };

    this.ws.onclose = (event) => {
      this.stopHeartbeat();
      if (!event.wasClean) {
        this.reconnectWithBackoff();
      }
    };
  }

  private startHeartbeat() {
    // Send ping every 30 seconds to keep connection alive
    this.heartbeatInterval = window.setInterval(() => {
      if (this.ws?.readyState === WebSocket.OPEN) {
        this.ws.send(JSON.stringify({ type: 'ping' }));
      }
    }, 30000);
  }

  private reconnectWithBackoff() {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      console.error('Max reconnection attempts reached. Falling back to polling.');
      this.fallbackToPolling();
      return;
    }

    // Exponential backoff: 1s, 2s, 4s, 8s... capped at 30s
    const delay = Math.min(
      1000 * Math.pow(2, this.reconnectAttempts),
      30000
    );

    // Add jitter to prevent thundering herd
    const jitter = delay * 0.3 * Math.random();

    setTimeout(() => {
      this.reconnectAttempts++;
      this.connect(this.currentToken);
    }, delay + jitter);
  }

  private fallbackToPolling() {
    // If WebSocket fails persistently, fall back to HTTP polling
    setInterval(async () => {
      const newPosts = await fetchNewPosts(this.lastSeenTimestamp);
      if (newPosts.length > 0) {
        feedStore.addNewPosts(newPosts);
      }
    }, 30000); // Poll every 30 seconds
  }
}

// All messages follow this envelope
type WSMessage =
  | { type: 'new_post'; payload: FeedPost }
  | { type: 'post_deleted'; payload: { postId: string } }
  | { type: 'reaction_update'; payload: {
      postId: string;
      reactions: ReactionSummary;
    }}
  | { type: 'comment_added'; payload: {
      postId: string;
      comment: Comment;
      newCount: number;
    }}
  | { type: 'typing_indicator'; payload: {
      postId: string;
      user: User;
      isTyping: boolean;
    }}
  | { type: 'pong' }
  | { type: 'error'; payload: { code: string; message: string } };

// Immediately prepend new posts
ws.onNewPost((post) => {
  feedStore.prependPost(post);
});

// Buffer new posts, show a clickable banner
ws.onNewPost((post) => {
  feedStore.incrementNewPostsCount();
  feedStore.bufferNewPost(post);
});

// In the UI:
function NewPostsBanner() {
  const { newPostsCount, showNewPosts } = useFeedStore();

  if (newPostsCount === 0) return null;

  return (
    <button
      onClick={showNewPosts}
      className="sticky top-16 z-10 w-full bg-primary text-primary-foreground
                 py-2 rounded-lg shadow-md animate-slide-down"
    >
      {newPostsCount} new {newPostsCount === 1 ? 'post' : 'posts'} — Click to see
    </button>
  );
}

// When clicked:
function showNewPosts() {
  const buffered = feedStore.getBufferedPosts();
  feedStore.prependPosts(buffered);
  feedStore.clearBuffer();
  window.scrollTo({ top: 0, behavior: 'smooth' });
}

import { useVirtualizer } from '@tanstack/react-virtual';

function VirtualizedFeed({ posts }: { posts: FeedPost[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: posts.length,
    getScrollElement: () => parentRef.current,
    estimateSize: (index) => {
      // Estimate based on post type
      const post = posts[index];
      switch (post.content.type) {
        case 'text': return 200;
        case 'image': return 500;
        case 'video': return 450;
        case 'link': return 350;
        default: return 300;
      }
    },
    overscan: 3,  // Render 3 extra items above/below viewport
  });

  return (
    <div ref={parentRef} style={{ height: '100vh', overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize() }}>
        {virtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.key}
            style={{
              position: 'absolute',
              top: virtualRow.start,
              width: '100%',
            }}
          >
            <FeedPost post={posts[virtualRow.index]} />
          </div>
        ))}
      </div>
    </div>
  );
}

function useInfiniteScroll(
  loadMore: () => Promise<void>,
  hasMore: boolean
) {
  const sentinelRef = useRef<HTMLDivElement>(null);
  const isLoadingRef = useRef(false);

  useEffect(() => {
    const sentinel = sentinelRef.current;
    if (!sentinel || !hasMore) return;

    const observer = new IntersectionObserver(
      async (entries) => {
        if (entries[0].isIntersecting && !isLoadingRef.current) {
          isLoadingRef.current = true;
          await loadMore();
          isLoadingRef.current = false;
        }
      },
      {
        root: null,
        rootMargin: '400px',  // Trigger 400px BEFORE user reaches bottom
        threshold: 0,
      }
    );

    observer.observe(sentinel);
    return () => observer.disconnect();
  }, [loadMore, hasMore]);

  return sentinelRef;
}

// Usage:
function FeedList() {
  const { posts, fetchMore, hasMore, isLoadingMore } = useFeedStore();
  const sentinelRef = useInfiniteScroll(fetchMore, hasMore);

  return (
    <div role="feed" aria-busy={isLoadingMore}>
      {posts.map((post) => (
        <article key={post.id} aria-posinset={/* position */} aria-setsize={-1}>
          <FeedPost post={post} />
        </article>
      ))}

      {/* Invisible sentinel element */}
      <div ref={sentinelRef} aria-hidden="true" style={{ height: 1 }} />

      {isLoadingMore && <FeedSkeleton count={3} />}
    </div>
  );
}

async function reactToPost(postId: string, reaction: ReactionType) {
  const previousPost = feedStore.getPost(postId);

  // Step 1: Optimistically update UI immediately
  feedStore.updatePost(postId, {
    hasUserReacted: reaction,
    reactions: {
      ...previousPost.reactions,
      total: previousPost.reactions.total + 1,
      byType: {
        ...previousPost.reactions.byType,
        [reaction]: (previousPost.reactions.byType[reaction] || 0) + 1,
      },
    },
  });

  try {
    // Step 2: Send to server
    const response = await api.post(`/posts/${postId}/reactions`, {
      reactionType: reaction,
    });

    // Step 3: Reconcile with server response (source of truth)
    feedStore.updatePost(postId, {
      reactions: response.reactions,
    });
  } catch (error) {
    // Step 4: Rollback on failure
    feedStore.updatePost(postId, {
      hasUserReacted: previousPost.hasUserReacted,
      reactions: previousPost.reactions,
    });

    toast.error('Failed to react. Please try again.');
  }
}

function PostImage({ image }: { image: MediaItem }) {
  const [loaded, setLoaded] = useState(false);

  return (
    <div
      className="relative bg-muted overflow-hidden"
      style={{
        // Prevent layout shift with aspect ratio box
        aspectRatio: `${image.width} / ${image.height}`,
      }}
    >
      {/* Low-quality placeholder (blurred thumbnail) */}
      {!loaded && (
        <img
          src={image.thumbnailUrl}
          alt=""
          className="absolute inset-0 w-full h-full object-cover blur-lg scale-105"
          aria-hidden="true"
        />
      )}

      {/* Full-quality image */}
      <img
        src={image.url}
        alt={image.altText}
        loading="lazy"
        decoding="async"
        onLoad={() => setLoaded(true)}
        className={`w-full h-full object-cover transition-opacity duration-300
          ${loaded ? 'opacity-100' : 'opacity-0'}`}
        sizes="(max-width: 680px) 100vw, 680px"
        srcSet={`
          ${image.thumbnailUrl} 320w,
          ${image.url}?w=680 680w,
          ${image.url}?w=1360 1360w
        `}
      />
    </div>
  );
}

// Feed container with proper ARIA semantics
<div
  role="feed"
  aria-label="News Feed"
  aria-busy={isLoading}
>
  {posts.map((post, index) => (
    <article
      key={post.id}
      aria-posinset={index + 1}
      aria-setsize={hasMore ? -1 : posts.length}
      aria-labelledby={`post-author-${post.id}`}
      tabIndex={0}
    >
      <header>
        <span id={`post-author-${post.id}`}>
          Post by {post.author.name}
        </span>
        <RelativeTime timestamp={post.createdAt} />
      </header>

      <PostBody content={post.content} />

      <footer>
        <button
          aria-pressed={!!post.hasUserReacted}
          aria-label={
            post.hasUserReacted
              ? `Remove ${post.hasUserReacted} reaction`
              : 'Like this post'
          }
        >
          Like ({post.reactions.total})
        </button>
      </footer>
    </article>
  ))}
</div>

// Cleanup videos when scrolled off-screen
useEffect(() => {
  return () => {
    // Pause and release video resources when post unmounts
    videoRef.current?.pause();
    videoRef.current?.removeAttribute('src');
    videoRef.current?.load(); // Forces resource release
  };
}, []);

// Re-sync when tab becomes visible
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    // Check WebSocket health
    if (ws.readyState !== WebSocket.OPEN) {
      ws.reconnect();
    }

    // Fetch any posts we missed
    feedStore.fetchNewPostsSince(feedStore.lastSeenTimestamp);
  }
});

// Solution: AbortController + request deduplication
const pendingReactions = new Map<string, AbortController>();

async function reactToPost(postId: string, reaction: ReactionType | null) {
  // Cancel any pending reaction for this post
  const existing = pendingReactions.get(postId);
  if (existing) {
    existing.abort();
  }

  const controller = new AbortController();
  pendingReactions.set(postId, controller);

  try {
    await api.post(`/posts/${postId}/reactions`, {
      reactionType: reaction,
    }, { signal: controller.signal });
  } catch (error) {
    if (error.name !== 'AbortError') {
      // Real error — rollback
      rollbackReaction(postId);
    }
  } finally {
    pendingReactions.delete(postId);
  }
}

// Solution: Code-split by post type and interaction
const VideoPlayer = lazy(() => import('./VideoPlayer'));
const ReactionPicker = lazy(() => import('./ReactionPicker'));
const CommentSection = lazy(() => import('./CommentSection'));
const LinkPreview = lazy(() => import('./LinkPreview'));

function FeedPost({ post }: { post: FeedPost }) {
  return (
    <article>
      <PostHeader author={post.author} time={post.createdAt} />

      {/* Only load the component needed for this post type */}
      <Suspense fallback={<ContentSkeleton type={post.content.type} />}>
        {post.content.type === 'video' && (
          <VideoPlayer video={post.content.video} />
        )}
        {post.content.type === 'link' && (
          <LinkPreview link={post.content.linkPreview} />
        )}
      </Suspense>

      <PostActions post={post} />

      {/* Comments only load when user clicks "View Comments" */}
      <Suspense fallback={<CommentSkeleton />}>
        {showComments && <CommentSection postId={post.id} />}
      </Suspense>
    </article>
  );
}