Comment system walk-through: threads, moderation states and re-renderable content

Goal

Let users post threaded comments that can be moderated before or after publication, edited, reported and removed, while the stored data stays safe to render years later.

Prerequisites

An identity for authors, a moderation policy (pre-moderation for new accounts, post-moderation for trusted ones), and a chosen input format (plain text or a Markdown subset).

Steps

1. Constraints: never store rendered HTML as the truth; removing a comment must not collapse the replies below it; every moderation action is attributable; reads are paginated and cheap.
2. Components: a write API with per-author rate limits; the store; a renderer that converts source text to HTML at read time into a cache that can be dropped; a moderation queue; a report endpoint; an audit of actions.
3. Data model: comment(id, thread_id, parent_id, path, depth, author_id, body_source, status: pending|visible|hidden|removed, created_at, edited_at); comment_revision(comment_id, body_source, edited_at); report(comment_id, reporter_id, reason, at); moderation_action(comment_id, moderator_id, action, reason, at). The materialised path of ancestor ids with a depth cap gives cheap subtree reads; paginate top-level comments by (created_at, id) and load replies per page.
4. Rendering: keep body_source authoritative and render through a sanitising pipeline whose output is only a cache. The OWASP XSS cheat sheet states that HTML sanitisation strips dangerous HTML and returns a safe string, and that sanitiser bypasses are discovered regularly, so the library must be patched; storing rendered HTML would freeze every past bypass into the data.
5. Moderation states: pending is visible only to its author; hidden keeps the node with a placeholder; removed by the author keeps the node if it has children and deletes it otherwise. Route to the queue by author trust, report count and simple heuristics (links, repeated text).
6. Failure modes: queue starvation (age-based priority, alert on age); report brigading (weight reporters by history, require a threshold before auto-hiding); very deep threads (depth cap and a "continue this thread" link); edits after approval (re-enter the queue when the text changed materially); an author deleting the account (pseudonymise the author, keep the node).
7. Measure: time in pending, reports per thousand comments, share hidden after a report, moderator actions per day, renderer errors.
8. Not first: votes and ranking, real-time updates, a machine-learning spam model, reputation levels, rich embeds, reactions.

Expected result

Every visible comment can be traced from source text to a moderation decision, threads keep their shape when nodes are removed, and a sanitiser fix applies to all history on the next render.

Limits and test basis

Proposed design, no measurements. Output encoding rules are in the XSS article; this walk-through covers the service around them.