Moderation System

1. Simple Feature Overview

The Moderation System lets your team review, approve, reject, and manage reader comments and interactions across the Hyphen platform. It protects your publication from spam, abusive content, and inappropriate behavior — while keeping the commenting experience smooth for genuine readers.

Every comment a reader posts on the Reader Portal flows through one pipeline: it is length-checked, scanned by the profanity filter and a multi-signal spam scorer, then either auto-approved, held for review, or auto-rejected based on your settings. Comments that need a human decision land in the moderation queue in the Admin Console, where moderators approve, reject, flag, hide, or mark them as spam. Readers can also report comments they find inappropriate, and persistent offenders can be warned or banned. Every action is written to a moderation log and the platform audit trail.

What You Can Do

How Moderation Works — The Big Picture

Reader writes a comment on an article (Reader Portal)
    ↓
System checks the comment against profanity and spam filters
    ↓
If "Require Approval" is ON → Comment goes to Pending status (not visible to other readers)
If "Require Approval" is OFF and filters pass → Comment is auto-Approved (visible immediately)
If filters flag the comment → Comment goes to Pending status for moderator review
    ↓
Moderator reviews the comment in the Admin Console Moderation page
    ↓
Moderator Approves → Comment becomes visible on Reader Portal
Moderator Rejects / Hides / Marks as Spam → Comment stays hidden from readers
    ↓
All actions are logged in the moderation log and audit trail

2. Who Should Use This Feature

3. Before You Begin

Before you can use the moderation features, make sure the following are in place:

Required Permissions

You need specific permissions assigned to your admin account. Ask an Admin to check your role in Settings > Admin Users.

Typical role assignments:

• Admin role: All permissions above
• Moderator role: moderation:read, moderation:approve, moderation:reject
• Viewer / Analyst role: moderation:read only (view but cannot take action)

Required Platform Configuration

4. Key Terms in Simple Language

How It Works (Behind the Scenes)

This section traces a comment and a report end-to-end, from a reader's click on the Reader Portal to what a moderator sees in the Admin Console — and back to what other readers see.

The data flow

1. Reader submits — A logged-in reader posts a comment (or a reply) on a published article, or taps Report on an existing comment. The Reader Portal (:3002) calls the platform API.
2. API validates and scores — The comment endpoint (/api/articles/[slug]/comments) loads your current moderation settings and the profanity word list from PostgreSQL, then runs validateCommentContent(). This single function enforces length, link/image policy, the profanity filter, and the multi-signal spam scorer.
3. Status is decided — Based on the validation result and the Require Approval setting, the comment is written to the comments table in PostgreSQL with one of three starting statuses: approved (clean + approval off), pending (held for review), or it is rejected outright before saving (length/link/image/profanity hard-fail).
4. Reports are stored — A report is written to the content_reports table with status = open, a reason (one of seven enum values), the reporter's identity, and the target comment. The target comment's report counter increments.
5. Admin queue surfaces the work — The Admin Console (:3000) Moderation page reads comments and content_reports to populate the Comments, Reports, and Users tabs and the four stat cards.
6. Moderator acts — Approve / reject / flag / spam / hide / restore / edit / delete on a comment, or resolve / dismiss on a report. The action updates the row's status, writes a ModerationLog entry (action, resource, previous → new status, actor, reason), and writes a platform audit entry (with IP and user agent).
7. Portal reflects the result — The public GET endpoint returns only approved comments, so an approval makes a comment appear and a reject/spam/hide makes it disappear. The article's comment count tracks approved comments only.

Where things live: Settings, the profanity word list, comments, reports, and moderation logs are all stored in PostgreSQL via Prisma. Article content itself lives in Strapi (:1337); the moderation system references articles by ID/slug but does not store article bodies.

Concepts: Spam Scoring, Reports & Moderation Workflow

The multi-signal spam scorer

The spam filter does not rely on a single rule. It runs the comment text through a set of independent signals, each contributing points to a cumulative spam score (capped at 100). A comment is treated as spam when its score is greater than or equal to the Spam Threshold you configure. Because the threshold is a floor the score must reach, a higher threshold means fewer comments are caught (more lenient) and a lower threshold catches more (stricter).

When the score reaches the threshold, the comment is flagged (sent to the queue as pending) rather than silently rejected — a human always makes the final call on spam-scored comments. The matched reasons are recorded so a moderator can see why it was flagged.

Tuning tip: The default Spam Threshold is 70. A clean comment scores 0. A typical promotional comment ("Click here, buy now, guaranteed!") can easily stack 75+ points and trip the threshold. If legitimate comments are being flagged, raise the threshold; if junk is slipping through, lower it.

The profanity filter

Independently of the spam scorer, every comment is checked against your database-backed profanity word list. Each word carries a severity (low / medium / high). The Profanity Action setting decides the outcome:

• Flag — send the comment to the queue (pending) for review.
• Auto-reject — reject the comment at submission time; it is never saved as visible.
• Censor — replace the matched word(s) with asterisks and allow the comment through.

Profanity and spam are evaluated together in validateCommentContent(). A hard violation (length, disallowed link/image, or profanity set to auto-reject) wins and rejects the comment; otherwise a flag from either filter holds it as pending.

Comment lifecycle

The six comment statuses below are the exact values stored in the database (CommentStatus enum): pending, approved, rejected, flagged, spam, hidden.

Content reporting

A reader report is a separate record (content_reports) with its own lifecycle, independent of the comment's status. A report carries a type (content or user), a reason, and a status, and it points at a target (a comment, article, or user).

The seven report reasons are the exact ReportReason enum values: spam, harassment, hate_speech, misinformation, copyright, inappropriate, other. The four report statuses are the ReportStatus enum: open, reviewing, resolved, dismissed.

User moderation (warn / ban)

Beyond individual comments, moderators act on the reader account. A warning is a logged, non-blocking notice. A ban stops the reader from posting any new comment — at submission time the API checks the reader's ban state and returns a restriction message. Ban types include comment, platform, temporary, and permanent; a reason is required and stored on the reader's record. Existing approved comments stay visible unless separately moderated.

Appeals

There is no built-in reader-facing appeal flow in the current implementation. Appeals are handled through your existing support channel; a moderator with moderation:ban_user can then unban the reader. See Current Known Limitations for the full picture.

5. Step-by-Step Setup Guide

5.1 Accessing the Moderation Page

1. Log in to the Admin Console.
2. In the left sidebar, navigate to Readers > Moderation.
3. The Moderation page opens with a shield icon, titled "Moderation" with the subtitle "Monitor and moderate reader interactions."
4. If you see an "Access Denied" message, your account does not have the moderation:read permission. Contact an Admin to update your role.

Note: There is also an older route at /moderation which automatically redirects to the current location at /readers/moderation.

5.2 Understanding the Moderation Dashboard

1

2

3

Stat cards — pending comments, reported content, flagged users, and total actions at a glance

1Comments tab — review and moderate reader comments

2Reports tab — handle content and user reports

3Users tab — manage warned or banned users

At the top of the Moderation page, you will see four stat cards giving you a quick snapshot:

Below the stat cards, you will see four tabs:

5.3 Configuring Moderation Settings

Permission required: settings:update

Click the Settings tab on the Moderation page. You will see several groups of settings:

Comment Settings

Links & Media

Profanity Filter

Spam Filter

User Trust Settings

Notifications

To change any setting:

1. Go to the Settings tab.
2. Find the setting you want to change.
3. Toggle the switch, enter a new value, or select from the dropdown.
4. Click Save (or the setting may save automatically depending on the field).
5. Changes take effect immediately for all new comments.

5.4 Managing the Profanity Word List

Permission required: settings:update

The profanity word list is at the bottom of the Settings tab. This is a database-backed list of words that the profanity filter checks against.

Adding a Word

1. In the Settings tab, scroll to the Profanity Words section.
2. Type the word into the text field.
3. Select a severity level from the dropdown:
   • Low — Usually just flagged for review
   • Medium — Can trigger flag or censor depending on your Profanity Action setting
   • High — Typically auto-rejected or censored
4. Click Add.
5. The word appears in the list below. All words are stored in lowercase.

Removing a Word

1. Find the word in the profanity list (you can search/scroll).
2. Click the Delete or Remove button next to it.
3. The word is removed immediately.

Tip: Start with high-severity words that should always be caught, then add medium and low severity words as you learn what your community encounters.

5.5 Reviewing Comments in the Queue

Click the Comments tab. This is where you spend most of your moderation time.

Filtering the Queue

At the top of the Comments tab, you have three filter controls:

What Each Comment Card Shows

Each comment in the queue is displayed as a card with:

• Article title and slug — Which article the comment was posted on
• Author name — The reader's display name
• Date — When the comment was submitted
• Status badge — Color-coded: Pending (yellow), Approved (green), Rejected (red), Flagged (orange), Spam (gray), Hidden (gray)
• Report count — How many times readers have reported this comment
• Comment text — The full content of the comment
• Action buttons — The actions you can take (see next section)

Pagination

The queue shows 20 comments per page. Use the Previous and Next buttons at the bottom to navigate. You'll see "Page X of Y" to track your position.

Click the Refresh button to reload the queue with the latest comments.

5.6 Taking Action on Individual Comments

Each comment card has action buttons. The buttons available depend on the comment's current status and your permissions.

To take an action:

1. Find the comment in the queue.
2. Review the comment text, author, and article context.
3. Click the appropriate action button.
4. For some actions, you may be prompted to add a moderation note explaining your decision.
5. The comment's status updates immediately.

Important: When you approve a comment, the article's comment count increases by one. When you reject, hide, spam, or delete a previously approved comment, the count decreases by one.

5.7 Using Bulk Actions on Multiple Comments

When you have many comments to process at once (e.g., after a weekend), bulk actions save time.

1. In the Comments tab, you will see a checkbox next to each comment.
2. Use the Select All checkbox at the top to select all comments on the current page, or check individual comments.
3. Once at least one comment is selected, three bulk action buttons appear:
   • Approve — Approve all selected comments
   • Reject — Reject all selected comments
   • Spam — Mark all selected comments as spam
4. Click the desired action.
5. The system processes all selected comments. You will see a result showing how many succeeded and how many failed (if any).

Limit: You can bulk-moderate up to 100 comments at once.

5.8 Managing Content Reports

Click the Reports tab to see reports submitted by readers.

What a Report Shows

Each report includes:

Report Statuses Explained

Taking Action on Reports

For each report, you can:

1. Update Status — Change from Open to Reviewing to indicate you are working on it.
2. Resolve — Mark the report as resolved. You will be prompted to add a resolution note explaining what action was taken.
3. Dismiss — Mark the report as dismissed. You will be prompted to add a reason why no action was needed.

Typical report workflow:

1. Open the Reports tab.
2. Filter by Open status to see new reports.
3. Click on a report to see the details.
4. Read the reported content and the reporter's reason.
5. If action is needed, go to the Comments tab and reject/hide/spam the reported comment.
6. Come back to the report and click Resolve, adding a note like "Comment rejected — violated community guidelines."
7. If no action is needed, click Dismiss and add a reason like "Comment does not violate guidelines."

Note: Readers cannot see who reported a comment. Reporter identity is only visible to admin users.

5.9 Moderating Users (Warn, Ban, Unban)

Click the Users tab to see a list of readers who have comment activity.

What the Users Tab Shows

The Users tab displays a table with:

Using the User Moderation Panel

Click View next to any user to open the User Moderation Panel (a modal/slide-out). This shows:

• User information — Name, email, account details
• Statistics — Total comments, approved, rejected, flagged counts
• Active warnings — Any warnings currently on the account
• Active bans — Any bans currently in effect
• Recent comments — The user's latest comments

Actions Available in the User Moderation Panel

What happens when a reader is banned:

• The reader can no longer submit comments on any article.
• If they try to comment, they see a message: "Your account has been restricted from commenting."
• Their existing approved comments remain visible unless you separately reject or hide them.
• The ban reason is recorded in the system.

To ban a reader:

1. Open the Users tab.
2. Click View next to the reader.
3. In the User Moderation Panel, click Ban.
4. Select the ban type (e.g., Comment, Permanent).
5. Enter a reason for the ban.
6. Confirm the action.

To unban a reader:

1. Open the Users tab.
2. Find the banned reader (their status shows "Banned").
3. Click View.
4. Click Unban.
5. The reader can immediately start commenting again.

5.10 How Readers Submit Comments on the Reader Portal

Understanding the reader experience helps you moderate effectively.

1. A reader visits an article on the Reader Portal.
2. Below the article, they see the comment section (if commenting is enabled for that article).
3. The reader must be logged in to comment. If not logged in, they see a "Sign in" link.
4. They type their comment in the text box. The box shows:
   • Placeholder text: "Share your thoughts..."
   • A character counter (max 2,000 characters)
   • A Comment button
5. When they click Comment, the system:
   • Validates the comment length (minimum 10, maximum 2,000 characters)
   • Checks for banned words (profanity filter)
   • Checks for spam signals (spam filter)
   • Checks if the reader is banned
   • Checks the rate limit (max 10 comments per 15 minutes)
6. If the comment passes all checks:
   • If "Require Approval" is ON: The comment is saved as Pending. The reader sees: "Your comment has been submitted and is awaiting moderation."
   • If "Require Approval" is OFF and filters pass: The comment is saved as Approved and immediately visible to other readers.
   • If filters flag the comment: The comment is saved as Pending regardless of the approval setting.

Replying to comments:

• Readers can click Reply on any approved comment to write a threaded reply.
• Replies follow the same validation and moderation rules as top-level comments.
• The reply box shows the placeholder "Write a reply..."

5.11 How Readers Report Comments on the Reader Portal

1. Next to each comment, readers see a Report button.
2. Clicking it opens the Report Comment modal with the message: "Help us keep the community safe..."
3. The reader selects a reason by clicking one of seven radio buttons:
   • Spam
   • Harassment
   • Hate Speech
   • Misinformation
   • Copyright
   • Inappropriate
   • Other
4. Optionally, the reader adds details in the "Additional details (optional)" text box (max 1,000 characters).
5. They click Submit Report.
6. The report is created with status "Open" and appears in your Reports tab.
7. The reported comment's report count increases by one.

Protections against report abuse:

• A reader can only have one active (Open or Reviewing) report against the same comment. Duplicate reports are blocked with an error.
• Readers are limited to 5 reports per 15 minutes per IP address.

5.12 How Moderation Actions Affect Reader Portal Visibility

This is important to understand: only comments with "Approved" status are visible on the Reader Portal.

Article comment count: The number shown next to the article's comment count reflects only Approved comments. When you approve a comment, the count goes up by one. When you reject, hide, or spam an approved comment, the count goes down by one.

5.13 Audit Logging and Moderation History

Every moderation action is automatically recorded in two places:

Moderation Log

The moderation log captures:

• What action was taken (approve, reject, flag, spam, hide, restore, delete, edit, warn, ban, unban, resolve report, dismiss report)
• Which item was affected (the comment, report, or reader)
• Who performed the action (the admin user)
• Previous status and new status (e.g., pending → approved)
• Reason or note provided by the moderator
• When the action occurred

Audit Trail

All moderation actions are also logged in the platform's general audit trail system, which records:

• The action type (e.g., moderation_approve, moderation_reject, moderation_ban_reader)
• The actor (admin user)
• IP address and user agent
• Timestamp

This dual logging means you have both a moderation-specific history and a platform-wide audit trail for compliance and accountability.

5.14 GDPR and Compliance Considerations

When handling moderation, keep these compliance points in mind:

6. How to Verify It Worked

After setting up or using moderation features, use these checks to confirm everything is working:

Settings Verification

Comment Moderation Verification

Report Verification

User Moderation Verification

7. Worked Examples

7.1 Example 1: Reviewing and Approving a New Comment

Scenario: A reader named Priya posted a comment on an article titled "The Future of Urban Fiction." Your settings have "Require Approval" turned on, so the comment is waiting in the queue.

Steps:

1. Log in to the Admin Console.
2. Navigate to Readers > Moderation.
3. Check the stat cards — you see Pending Comments: 3, confirming there are comments waiting.
4. Click the Comments tab (it should be selected by default).
5. Set the Status dropdown to Pending to focus on comments needing review.
6. Find Priya's comment card. You can see:
   • Article: "The Future of Urban Fiction"
   • Author: Priya
   • Status: Pending (yellow badge)
   • Content: "This article really resonated with me. The parallels between urban fiction and real city life are brilliantly explored."
7. The comment is thoughtful and appropriate. Click the Approve button.
8. The status badge changes to Approved (green).
9. Verify on Reader Portal: Open the article "The Future of Urban Fiction" on the Reader Portal. Scroll to the comments section. Priya's comment should now be visible with her name, the date, and the comment text. The article's comment count should have increased by one.

7.2 Example 2: Rejecting Inappropriate Content and Verifying Reader Portal

Scenario: A reader named Vikram posted a comment containing offensive language on a poetry article. The profanity filter flagged it, but you need to review and take final action.

Steps:

1. Navigate to Readers > Moderation.
2. Notice the Pending Comments stat card shows pending items.
3. In the Comments tab, toggle Flagged Only to On to see only flagged comments.
4. Find Vikram's comment. You can see:
   • Status: Pending (it was flagged by the profanity filter)
   • Content contains offensive language
   • Report count may show 0 (it was caught by the filter, not reported by readers)
5. Click Reject.
6. Optionally add a moderation note: "Contains offensive language — violates community guidelines."
7. The status changes to Rejected (red badge).
8. Verify on Reader Portal: Open the article on the Reader Portal. Vikram's comment should not appear anywhere in the comment section. The comment count should not include this comment.
9. Consider user action: If Vikram has a pattern of inappropriate comments, click View User on his comment card to open the User Moderation Panel. Review his history. If warranted, click Warn or Ban.

7.3 Example 3: Restoring a Comment That Was Moderated Incorrectly

Scenario: A colleague accidentally rejected a perfectly fine comment from a reader named Anita. The customer success team received a complaint and asked you to fix it.

Steps:

1. Navigate to Readers > Moderation.
2. In the Comments tab, set the Status dropdown to Rejected to find Anita's comment.
3. Use the Search box to type "Anita" to narrow the results.
4. Find Anita's comment. Read the content to confirm it is indeed appropriate.
5. Click Restore.
6. The status changes to Pending (the comment re-enters the review queue).
7. Now click Approve to make the comment visible to readers.
8. The status changes to Approved (green).
9. Verify on Reader Portal: Open the article where Anita commented. Her comment should now appear in the comment section.
10. Inform the team: Let the customer success team know the comment has been restored and is now visible.

Note: The moderation log will show the full history: original rejection, the restore action, and the approval — including who performed each action and when.

7.4 Example 4: Checking Moderation History for a Specific Comment

Scenario: Your editorial lead asks about a comment on a sensitive political article that was reportedly removed. They want to know who removed it, when, and why.

Steps:

1. Navigate to Readers > Moderation.
2. In the Comments tab, set the Status dropdown to All (to search across all statuses, including rejected and hidden).
3. Use the Search box to search for the article title or the commenter's name.
4. Find the comment in question. Note its current status (e.g., Rejected or Hidden).
5. The comment card shows:
   • Who moderated it (the "Moderated by" field)
   • When it was moderated (the moderation timestamp)
   • The moderation note (if the moderator added one)
6. For the full audit trail, the moderation log records every status change, including:
   • The previous status and new status
   • The admin user who took the action
   • The timestamp
   • Any reason provided
7. Report back to the editorial lead with the specific details: "The comment was rejected by [Moderator Name] on [Date] with the note: [reason]."

Tip: If you need to verify this through the platform's broader audit system, check the Audit section which captures all moderation actions with IP address and timestamp details.

7.5 Example 5: Troubleshooting a Missing or Still-Visible Comment

Scenario A — Comment not showing in moderation queue:

A reader emails saying they posted a comment but it never appeared. You check the moderation queue and don't see it.

Troubleshooting steps:

1. Check if commenting is enabled: Go to Moderation > Settings tab. Confirm "Comments Enabled" is On.
2. Check the platform feature flag: Confirm featureFlags.comments is true.
3. Check all statuses: In the Comments tab, set Status to All and search for the reader's name. The comment might already have been auto-rejected by the spam or profanity filter.
4. Check if the reader is banned: Go to the Users tab, search for the reader. If their status is "Banned," their comment submission would have been blocked entirely (it never entered the system).
5. Check rate limits: If the reader posted many comments quickly (more than 10 in 15 minutes), subsequent comments would have been rejected with a rate limit error.
6. Check comment length: If the reader's comment was shorter than the minimum length (default 10 characters) or longer than the maximum (default 2,000 characters), it would have been rejected at submission time.

Scenario B — Comment still visible after rejection:

You rejected a comment but a reader reports it is still visible on the Reader Portal.

Troubleshooting steps:

1. Verify the rejection: Go to Moderation > Comments, search for the comment. Confirm its status is Rejected (not still Pending or Approved).
2. Check for caching: The Reader Portal may be showing a cached version of the page. Ask the reader to refresh the page or try in an incognito/private browser window.
3. Check the correct article: Confirm you rejected the comment on the correct article. The reader may be looking at a different article.
4. Check for duplicates: The reader may have posted the same comment twice. Search for similar content in the queue — there may be a second copy that is still Approved.

8. Common Mistakes and How to Fix Them

Configuration Reference

This is the authoritative, field-by-field reference for everything you can configure in the Moderation system. "Where configured" tells you whether a setting lives in the Moderation > Settings UI or is backend/enum-defined (fixed values you select from, not free-form configuration). RBAC roles map to the permission required to change the setting.

Comment & approval settings

Profanity filter

Spam filter

Notifications

Report reason types (fixed enum)

Moderation actions on comments (fixed)

Report actions (fixed)

User moderation options (fixed)

Rate limits (fixed, backend)

Note: Reader-facing rate limits (comments and reports) are enforced by a Redis-backed limiter with an in-memory fallback, so limits hold consistently across multiple server instances.

Dependencies & Impact

The Moderation system does not operate in isolation. Understanding its connections helps you predict the downstream effect of a moderation action and diagnose issues quickly.

Impact of common actions:

• Approving a comment makes it publicly visible and increments the article's comment count.
• Rejecting / hiding / spamming an approved comment removes it from the portal and decrements the count.
• Banning a reader immediately blocks new submissions but leaves their existing approved comments untouched.
• Deleting a comment is irreversible (no soft-delete / trash).

FAQ

Known Limitations

The following limitations exist in the current implementation. They are noted here so you know what to expect and can plan workarounds where needed.

This guide reflects the current Moderation module implementation. If you notice any behavior that differs from what is described here, please contact the platform team for clarification.