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.

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

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