Description
Public Comments and Moderation add threaded audience input to rows served by a Dotabase publication. Visitors can list visible comments, verify an email address, create a bounded comment, and report inappropriate content. A live same-origin Dots session or a signed verified-email proof supplies admission identity; unattributable submissions are refused rather than stored anonymously.
Public responses expose a PII-stripped comment projection. Comment creation passes through spam handling and may land as visible or withheld. Authenticated workspace operators can hide a comment, list comments by row or status, and inspect the reported-comment queue. Every row-scoped action shares the publication visibility and comments-enabled gate.
Selling Points
- Turns published rows into a conversation surface while keeping authorship admission explicit.
- Supports outside visitors through email verification without requiring a full Dots account.
- Gives operators practical moderation controls: hide, filter, inspect reports, and contain suspected spam.
- Removes email and internal identifiers from public payloads, preserving useful attribution without exposing PII.
- Uses the same fail-closed publication resolver as public reads, so hidden or unpublished rows cannot be discovered through comments.
User Story
A customer reading a published roadmap item wants to explain why it matters. They verify their email once, submit a comment, and see it appear under the row unless spam checks withhold it. Another visitor reports an abusive reply. A workspace moderator opens the report queue and hides that exact comment from the public list.
Extension Surface
This feature is configurable. Publication owners enable the comments engagement flag, and deployments configure email delivery plus spam thresholds. packages/api/src/routes/comments.ts exposes public and authenticated moderation operations. Comment body shape, identity methods, and moderation statuses are closed contracts; there is no external comment-provider registration point.
Capabilities & Limits
- Lists and creates public comments with session or verified-email admission.
- Supports single-use email verification, signed proof cookies, visitor reports, hiding, and moderation queues.
- Applies bounded bodies, spam state, PII-safe public projection, ETags, and public rate limits.
- Limit: email verification is unavailable when the deployment has no mail transport.
- Limit: moderation hides comments; it does not provide a general-purpose discussion forum or arbitrary nested thread model.
Implementation Map
packages/api/src/routes/comments.tspackages/api/src/public/comment-email-verifier.tspackages/api/src/public/identity.tspackages/api/src/routes/public.tspackages/api/src/app.ts