Design a Threaded Discussion Forum (Reddit)

Post Service

Handles post authoring, validation, media ingestion, and event broadcasting:

• Create post: Validates content length and mandatory subreddit flair, uploads media attachments to S3, persists the record to PostgreSQL (sharded by subreddit_id), and publishes a post-events message to Kafka.
• Post types: Text, link, image, video, and poll submissions, each stored with type-specific metadata schemas.
• Flair: Enforces per-subreddit tag taxonomies such as Discussion, Question, or News.
• Cross-posting: Creates an independent post record in the target subreddit referencing the original through crosspost_parent_id. Vote scores, comments, and community moderation remain fully isolated.
• Awards & gilding: Handles community awards via giveAward, validating user coin balance, recording the transaction in the awards table, incrementing posts.award_count, updating Redis awards hash caches, and publishing an award-events message to Kafka.
• Soft delete & removal: Preserves tombstone records to maintain comment tree referential integrity, replacing the author name and content body with "[deleted]". Emits a post-events removal message that triggers eviction from Redis sorted sets (ZREM), invalidation of cached home feeds, purging of CDN edge cache tags, and de-indexing from Elasticsearch.

Subreddit Service

Manages community lifecycles, subscriber memberships, access policies, and moderation tooling:

• Community lifecycle: Oversees subreddit creation, customizable community rules, moderator assignments, and user ban enforcement.
• Membership tracking: Maintains the user_subreddits relationship table, which the Feed Service queries to assemble personalized home feeds.
• Access control: Supports public browsing, restricted posting where only approved contributors publish, and private invite-only subreddits.
• Moderator actions: Provides interfaces to remove policy-violating posts and comments, ban bad actors, pin announcements, and configure AutoModerator regex filters.

Comment Service

Orchestrates comment lifecycle operations, tree indexing, and branch retrieval:

• Materialized path storage: Encodes lineage hierarchy using dotted string paths formatted with fixed-width 6-character zero-padded base-36 segments such as 000001.000003.000007 where depth is directly derived from string segment count.
• Concurrent sibling allocation: Allocates the next monotonic sibling segment under the parent using an atomic per-parent sequence (such as Redis counter seq:comment:{parent_id} or PostgreSQL atomic counter UPDATE comments SET child_seq = child_seq + 1 WHERE comment_id = ? RETURNING child_seq). For root comments, it allocates from seq:post:{post_id}. Sibling segments are formatted as fixed-width 6-character zero-padded base-36 identifiers (such as 000001, 000002, 00000Z), which support over 2.17B ($36^6$) siblings per parent while preserving strict ASCII lexicographical sort order. Appending this segment to the parent's path (parent.path + '.' + allocated_segment) ensures concurrent replies to the same parent receive distinct non-colliding paths without race conditions.
• Sorting modes & ranking consistency: Supports best sorting using materialized wilson_score, top sorting by net score, new sorting by timestamp, and controversial sorting using materialized controversial_score. Top-level comments (depth = 0) are queried using idx_post_wilson (ORDER BY wilson_score DESC) or idx_post_controversial (ORDER BY controversial_score DESC), while child branches are fetched by path prefix (WHERE post_id = ? AND path LIKE '000001.000003.%'). Within each branch, child comments are ordered by path for natural pre-order conversation tree rendering in the UI. A single SQL query with ORDER BY path, score does not produce a globally Wilson-sorted tree because child nodes must remain structurally grouped under their respective parents.
• Lazy loading: Returns top-level comments first and fetches nested reply subtrees on demand using cursor pagination on the path prefix.
• Awards & gilding: Bestows awards on comment nodes via giveAward, persisting to the awards table, incrementing comments.award_count, and dispatching an award-events message to Kafka.
• Soft delete: When a comment is removed, if it has child replies, its content is masked to "[deleted]" and is_removed = true to preserve path continuity for descendant replies, whereas a leaf node with no replies can simply be pruned.

Comment Tree Storage: Architectural Approaches

Modeling deeply nested comment trees requires balancing write latency against complex hierarchical reads:

Approach 1: Adjacency List (Simple Writes, Slow Deep Traversal)

-- Schema: comments (comment_id, post_id, parent_comment_id, ...)
-- Retrieving the full tree requires recursive CTEs or iterative round trips

Approach 2: Materialized Path (Recommended)

-- Schema: comments (comment_id, post_id, path, child_seq, wilson_score, controversial_score, ...)
-- path = "000001.000003.000007.00000F" (ordered lineage from root in 6-character base-36 segments)
-- Retrieve subtree: WHERE post_id = ? AND path LIKE '000001.000003.%'
-- Sorting by path yields pre-order traversal for natural UI rendering

Approach 3: Nested Set Model (Fast Reads, Heavy Write Amplification)

-- Schema: comments (comment_id, post_id, lft, rgt, ...)
-- Retrieve all descendants: WHERE lft > parent.lft AND rgt < parent.rgt
-- Inserting a comment requires locking and updating lft and rgt boundaries across the table

Approach 4: Closure Table (Flexible Queries, O(Depth) Insert Cost)

-- Schema: comment_tree (ancestor_id, descendant_id, depth)
-- Stores one row for every ancestor-descendant pairing
-- Enables fast traversal but incurs O(depth) record inserts for every reply

Recommendation: Adopt the Materialized Path pattern for a Reddit-scale system. It delivers efficient single-query subtree reads, simple append writes, and natural hierarchical sorting without recursive query overhead.

Vote Service

Processes high-throughput vote traffic while preventing write contention on relational rows:

• Throughput challenge: Ingesting 500M votes per day generates intense write contention (~6,000 votes/sec average, 30,000 peak) when thousands of users interact with the same viral post simultaneously.
• Atomic Lua CAS transition: Concurrent requests from the same user cannot both pass the Redis check. The Vote Service executes an atomic Lua script against user_votes:{user_id}:{entity_type}:{entity_id}:
  • Same direction: Returns an idempotent no-op without mutating state or re-emitting events.
  • New vote (was 0 or nil): Atomically sets the new direction (1 or -1) with a 30-day sliding TTL and generates net delta +1 or -1.
  • Changed vote (direction flip): Atomically replaces the old direction with the new direction and calculates net delta (+1 to -1 is -2, while -1 to +1 is +2).
  • Removed vote (direction 0): Atomically deletes the key and calculates net delta (+1 to 0 is -1, while -1 to 0 is +1).
• Durable source of truth & TTL fallback: Redis user-vote state acts as a fast serving and deduplication cache. PostgreSQL user_votes is the durable source of truth. If a Redis vote-state key is missing or expired, the service queries PostgreSQL first before applying the transition to prevent duplicate votes across TTL boundaries. The composite primary key (user_id, entity_type, entity_id) in PostgreSQL serves as the immutable authoritative backstop.
• Redis + Kafka failure semantics:
  1. The service applies the atomic CAS state change tentatively in Redis.
  2. It publishes an event payload to Kafka vote-events with acks=all: { event_id, user_id, entity_type, entity_id, old_direction, new_direction, delta, timestamp }.
  3. Kafka producer timeouts are treated as ambiguous outcomes, where event_id-based consumer idempotency makes replay or duplicate publication safe. The service reconciles Redis serving state with the durable event stream rather than assuming a timeout means the event was never committed. On definite pre-publish errors (such as local payload validation failure or client-side connection drops before dispatch), tentative Redis state is rolled back immediately and an HTTP 503 error is returned.
  4. On publication acknowledgement, the service immediately returns HTTP 200 with { accepted: true, voteState: new_direction, eventId, approximateScore }. Authoritative score updates remain strictly asynchronous.
• Downstream consumer processing & delta idempotency:
  • vote-db-writer: Transactionally deduplicates incoming events by event_id against the durable PostgreSQL processed_events table (enforced by PRIMARY KEY (consumer_group, event_id)) prior to upserting user_votes and executing UPDATE posts/comments SET score = score + delta. This ensures Kafka replays or consumer retries across the full 7-day retention window never apply duplicate score deltas.
  • vote-counter: Enforces fast-path event idempotency in Redis using an atomic check-and-set with a 7-day TTL matching Kafka topic retention (SET processed_events:counter:{event_id} 1 EX 604800 NX), backed by the durable PostgreSQL processed_events ledger on cache miss. If the event has already been recorded, counter application is skipped. Otherwise, it applies net delta increments to Redis score hashes at score:{entity_type}:{entity_id} via HINCRBY. The Redis counter cache is explicitly non-authoritative and continuously reconciled against PostgreSQL durable scores.
• Cache reconstruction: If Redis is lost, vote counts and user vote states are reconstructed from PostgreSQL user_votes or replayed from compacted Kafka event logs.

Ranking Algorithms: Deep Dive

Reddit relies on distinct scoring algorithms tailored to content types and freshness requirements:

Hot Ranking (Time-Decayed Post Scoring)

import math
from datetime import datetime

def hot_score(ups, downs, created_at):
    score = ups - downs
    order = math.log10(max(abs(score), 1))
    sign = 1 if score > 0 else -1 if score < 0 else 0

    # Epoch: Dec 8, 2005 (Reddit's birthday)
    epoch = datetime(2005, 12, 8, 7, 46, 43)
    seconds = (created_at - epoch).total_seconds()

    return round(sign * order + seconds / 45000, 7)

• Time dominance: Time is the primary ranking factor. A post published 12.5 hours earlier requires 10 times more net upvotes to maintain parity with a brand-new post.
• Logarithmic scale: Moving from 10 to 100 net votes contributes the exact same score increment as moving from 100 to 1,000 net votes, preventing popular threads from permanently dominating the front page.

Wilson Score ("Best" Comment Ranking)

import math

def wilson_score(ups, downs, confidence=0.95):
    n = ups + downs
    if n == 0:
        return 0
    z = 1.96  # 95% confidence
    p = ups / n

    return (p + z*z/(2*n) - z * math.sqrt((p*(1-p) + z*z/(4*n)) / n)) / (1 + z*z/n)

• Confidence interval lower bound: Solves the imbalance where a comment with a single upvote (100% positive) would otherwise rank above a proven comment with 100 upvotes and 1 downvote (99% positive).
• Sample size weighting: Calculates the lower bound of the 95% confidence interval for a Bernoulli parameter, stored in the materialized wilson_score column so that comments with larger sample sizes rank higher when their positive ratio is solid.

Controversial Ranking

def controversial_score(ups, downs):
    if ups <= 0 or downs <= 0:
        return 0
    magnitude = ups + downs
    balance = min(ups, downs) / max(ups, downs)
    return magnitude * balance

Evaluates total vote volume balanced against the ratio of minority to majority votes ((ups + downs) * (min(ups, downs) / max(ups, downs))), surfacing discussions with intense engagement and an even upvote/downvote split. For comments, this metric is materialized in the comments.controversial_score column and indexed with idx_post_controversial for efficient depth-0 subtree queries.

Rising Ranking (Velocity of Fresh Posts)

def rising_score(delta_ups_1h, delta_comments_1h, age_in_hours):
    # Evaluates short-term engagement velocity for posts created in the last 6 to 12 hours
    if age_in_hours > 12:
        return 0.0
    velocity = (delta_ups_1h * 2.0) + (delta_comments_1h * 3.0)
    time_decay = (age_in_hours + 0.5) ** 1.5
    return velocity / time_decay

Measures short-term engagement acceleration for posts submitted within the last 6 to 12 hours. Unlike Hot ranking (which applies logarithmic scaling across cumulative votes over a 12.5-hour half-life) or Top ranking (which tallies raw vote totals over fixed windows), Rising surfaces breakout discussions before they accumulate large aggregate totals. The Ranking Worker computes rising scores every 60 to 120 seconds and maintains the feed:sub:{subreddit_id}:rising sorted set in Redis.

New Ranking (Strict Chronological Ordering)

New ranking is strictly timestamp-based (using created_at epoch milliseconds or Snowflake ID timestamps). It is written once during post creation into feed:sub:{subreddit_id}:new and does not require continuous score recalculation by background ranking workers.

Ranking Worker

Asynchronously consumes event streams and recalculates ranking metrics without blocking the vote ingestion pipeline:

• Event stream consumption: Subscribes to Kafka vote-events and post-events topics across dedicated consumer groups.
• Score recalculation: Periodically recomputes logarithmic hot scores, short-term rising velocity, comment Wilson scores, and controversial scores. New sorting is strictly timestamp-based and bypassed by the scoring worker.
• Sorted set publication: Updates Redis sorted sets including feed:sub:{subreddit_id}:hot, feed:sub:{subreddit_id}:rising, feed:sub:{subreddit_id}:top, and feed:sub:{subreddit_id}:controversial.
• Asynchronous justification: A viral post receiving 30,000 votes per second cannot execute database row updates synchronously, meaning that offloading recalculation to background workers guarantees consistent API latencies.

Feed Service

Assembles personalized feeds by aggregating content across communities a user follows while strictly bounding compute overhead at 50M DAU:

• Active user bounding: Rather than refreshing all 50M users every 5 minutes (which would require 166,667 merges/sec), background merges are bounded strictly to the active user window (~2.5M concurrent users active within a 15-minute sliding window), requiring only ~8,300 merges/sec across horizontally sharded feed workers.
• Lazy recomputation for inactive users: Inactive users are not refreshed proactively, so their feeds are recomputed lazily on demand when they open the application.
• Bounded candidate pool: The merge job evaluates the user's top 50 subscribed subreddits, fetching the top 25 hot posts from each community's Redis sorted set (capping candidate IDs at 1,250). It interleaves posts by normalized hot score rather than naive alternation.
• Deduplication & caching: Deduplicates cross-posts using crosspost_parent_id and caches the assembled feed at feed:home:{user_id} with a 300-second TTL.
• Stale-while-revalidate: If a cached feed expires during a user request, the stale feed is served immediately while an asynchronous task regenerates the fresh feed in the background.
• Membership changes: Joining or leaving a subreddit invalidates or marks the user's home feed cache dirty, prompting a refreshed merge on the next view.

Search Service (Elasticsearch)

Powers full-text exploration across forum posts, comments, and community directories:

• Multi-index architecture & shard routing: Segregates documents across posts_index, comments_index, and subreddits_index. Posts are routed by subreddit_id to isolate community-scoped queries to a single shard, comments are routed by post_id to co-locate discussion trees, and subreddits use edge-ngram analyzers for instant prefix autocomplete.
• Query capabilities & ranking: Executes BM25 full-text scoring with title boosts, faceted filtering by community, author, post type, and creation time ranges, supporting sorting by relevance, recency (new), or net engagement (top).
• Asynchronous pipeline (search-indexer): A dedicated Kafka consumer group consumes post-events, comment-events, and subreddit metadata to update Elasticsearch indices in near real time. Content removals and soft deletions immediately mark documents unavailable or purge them from search results.

Moderation Pipeline

Processes content events asynchronously through automated inspection models and community review workflows:

• Spam detection model: Evaluates incoming posts for link farming, automated bot phrase repetition, and abnormal new-account posting velocity.
• Toxicity classification: Flags abusive or harassing content for immediate human review or automated quarantine.
• AutoModerator engine: Evaluates custom per-subreddit regular expressions and karma thresholds, automating actions such as filtering forbidden keywords or enforcing minimum account age.
• Moderation queue: Aggregates user-submitted flags into a prioritized triage queue for community volunteer moderators.
• Automated enforcement & propagation: When content is removed by moderators or automated classifiers, a removal event is published. Downstream consumers immediately remove the item from Redis ranked sorted sets (ZREM), invalidate active home feeds, purge CDN cache tags, and de-index the item in Elasticsearch.

Event Bus Design (Kafka)

The event bus decouples write-path producers from background consumers, absorbing traffic spikes seamlessly:

topics:
  post-events:
    description: "New post publications, content edits, soft deletions, and removals"
  comment-events:
    description: "New comment submissions, nested replies, edits, and deletions"
  vote-events:
    partitions: 128
    partition_key: "entity_id (post_id or comment_id to preserve per-entity vote ordering)"
    retention: "7 days"
    replication_factor: 3
    min_insync_replicas: 2
  award-events:
    partitions: 32
    partition_key: "entity_id (post_id or comment_id)"
    description: "Community awards and gilding carrying award_id, entity_type, entity_id, giver_user_id, award_type, and coin_cost"

producer_configuration:
  acks: "all"
  idempotence: true
  payload_schema:
    event_id: "uuid"
    user_id: "int64"
    entity_type: "post | comment"
    entity_id: "int64"
    old_direction: "1 | -1 | 0"
    new_direction: "1 | -1 | 0"
    delta: "int16"
    timestamp: "int64"

consumer_groups:
  vote-db-writer:
    purpose: "Persist durable vote records to PostgreSQL source of truth (atomically checks processed_events table before upserting user_votes and applying score deltas)"
  vote-counter:
    purpose: "Apply atomic counter updates to Redis score hashes (score:post:{id}, score:comment:{id}) deduplicating event_id via Redis SET processed_events:counter:{event_id} 1 EX 604800 NX (7 days matching Kafka retention) with PostgreSQL processed_events ledger fallback"
  ranking-worker:
    purpose: "Recompute hot, top, rising, and controversial scores for Redis feed sorted sets (new sort uses created_at directly)"
  search-indexer:
    purpose: "Consume post-events, comment-events, and community metadata to update Elasticsearch indices near real time"
  award-processor:
    purpose: "Persist award records to PostgreSQL awards table, increment entity award_count, update Redis awards hash, and attribute karma"
  moderation:
    purpose: "Feed automated spam ML models, toxicity classifiers, and moderator report queues"

execution_paths:
  synchronous_path: "Atomic Redis Lua CAS state transition, publish vote-events to Kafka with acks=all, return 200 within 50ms"
  asynchronous_path: "Perform database batch writes, counter refreshes, search indexing, and feed recalculation off the critical path"
  failure_semantics: "Kafka producer timeouts are treated as ambiguous outcomes, where event_id-based consumer idempotency makes replay or duplicate publication safe. The service reconciles Redis serving state with the durable event stream rather than assuming a timeout means the event was never committed. On definite pre-publish errors, Redis state is rolled back immediately."
  dead_letter_queue: "vote-events-dlq routed after 3 retries, raising an alert if consumer lag exceeds 60 seconds"