Repository docs from .qoder/repowiki

Content Moderation States

Referenced Files in This Document

• content-moderation.controller.ts
• content-moderation.service.ts
• content-moderation.schema.ts
• post.table.ts
• auth.table.ts
• user.adapter.ts
• ReportPost.tsx
• moderation.ts
• moderation.ts

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

This document explains the content moderation states and their management across the platform. It covers the three content states (active, banned, shadow_banned) and their impact on visibility, user experience, and safety. It documents state transitions, best-effort handling for concurrent operations, administrative controls, persistence mechanisms, and real-time propagation to clients. Examples illustrate when each state is applied, automatic state changes, and manual intervention procedures.

Project Structure

The moderation system spans backend controllers and services, database tables, frontend utilities, and admin UI components:

• Backend: controllers and services manage state transitions for posts and comments.
• Database: tables persist moderation flags for posts and user blocking/suspension.
• Frontend: utilities and API wrappers support moderation-aware rendering and requests.
• Admin: UI components orchestrate moderation actions and report resolution.

graph TB
subgraph "Admin UI"
RP["ReportPost.tsx"]
end
subgraph "Web Frontend"
MU["moderation.ts (utils)"]
MA["moderation.ts (api)"]
end
subgraph "Server"
MC["content-moderation.controller.ts"]
MS["content-moderation.service.ts"]
SC["content-moderation.schema.ts"]
end
subgraph "Database"
PT["post.table.ts"]
AT["auth.table.ts"]
UA["user.adapter.ts"]
end
RP --> MC
MU --> MA
MA --> MC
MC --> MS
MS --> PT
MS --> UA
UA --> AT

Diagram sources

• content-moderation.controller.ts
• content-moderation.service.ts
• content-moderation.schema.ts
• post.table.ts
• auth.table.ts
• user.adapter.ts
• ReportPost.tsx
• moderation.ts
• moderation.ts

Section sources

• content-moderation.controller.ts
• content-moderation.service.ts
• content-moderation.schema.ts
• post.table.ts
• auth.table.ts
• user.adapter.ts
• ReportPost.tsx
• moderation.ts
• moderation.ts

Core Components

• Moderation states for content:
  • active: visible and searchable.
  • banned: hidden from public view; reported as removed.
  • shadow_banned: hidden from public view but not reported as removed; used to hide content without explicit notice.
• Moderation states for users:
  • blocked: account-level restriction; can be permanent or suspended until a specified date.
• Controllers and services:
  • Controllers validate inputs and delegate to services.
  • Services enforce state transitions, update persistence, and resolve related reports.
• Persistence:
  • Posts table stores isBanned and isShadowBanned flags.
  • Auth table stores banned, banReason, and banExpires for user-level moderation.
• Frontend and Admin:
  • Admin UI triggers moderation actions and updates report statuses.
  • Web utilities/API wrappers integrate moderation-aware logic.

Section sources

• content-moderation.schema.ts
• post.table.ts
• auth.table.ts
• content-moderation.controller.ts
• content-moderation.service.ts
• ReportPost.tsx

Architecture Overview

The moderation flow connects admin actions, frontend requests, backend controllers, services, and persistence. It ensures best-effort handling for concurrent operations and updates related reports upon state changes.

sequenceDiagram
participant Admin as "Admin UI (ReportPost.tsx)"
participant API as "Web API (moderation.ts)"
participant Ctrl as "Controller (content-moderation.controller.ts)"
participant Svc as "Service (content-moderation.service.ts)"
participant DB as "DB (post.table.ts, auth.table.ts)"
Admin->>Ctrl : PUT /posts/ : postId/state {state}
Ctrl->>Svc : moderateContent(targetId, type, action)
Svc->>DB : Update flags (isBanned/isShadowBanned)
DB-->>Svc : Updated record
Svc-->>Ctrl : Result with post/comment state
Ctrl-->>API : HTTP 200 OK
API-->>Admin : Success response

Diagram sources

• ReportPost.tsx
• moderation.ts
• content-moderation.controller.ts
• content-moderation.service.ts
• post.table.ts

Detailed Component Analysis

Content Moderation States and Implications

• active
  • Visibility: Publicly visible.
  • Impact: Normal engagement, ranking, and discoverability.
  • Trigger: Uploading content, unban operations, shadow_unban.
• banned
  • Visibility: Hidden from public view; reported as removed.
  • Impact: No engagement; potential appeal process.
  • Trigger: Manual moderation action or policy violation.
• shadow_banned
  • Visibility: Hidden from public view; not reported as removed.
  • Impact: Reduced risk of user awareness while suppressing harmful content.
  • Trigger: Administrative discretion for sensitive cases.

Examples of application:

• Active: New posts awaiting review become active after approval.
• Banned: Posts violating community guidelines are banned.
• Shadow banned: Posts deemed sensitive but not yet warranting public removal.

Automatic state changes:

• Shadow bans may be applied automatically by content filters prior to manual moderation.
• Related reports are resolved when shadow bans are applied.

Manual intervention:

• Admins can change states via the admin UI, which calls backend endpoints to update moderation state and report status.

Section sources

• content-moderation.schema.ts
• content-moderation.controller.ts
• content-moderation.service.ts
• ReportPost.tsx

State Transition Logic

The controller enforces mutually exclusive transitions:

• active: clears bans and shadow bans.
• banned: clears shadow bans, applies ban.
• shadow_banned: clears ban, applies shadow ban.

flowchart TD
Start(["Transition Request"]) --> Choose{"Target Type"}
Choose --> |Post| PostFlow["Post State Logic"]
Choose --> |Comment| CommentFlow["Comment State Logic"]
PostFlow --> A1["state=active<br/>unban + shadowUnban"]
PostFlow --> B1["state=banned<br/>shadowUnban + ban"]
PostFlow --> C1["state=shadow_banned<br/>unban + shadowBan"]
CommentFlow --> A2["state=active<br/>unban"]
CommentFlow --> B2["state=banned<br/>ban"]
A1 --> Done(["Success"])
B1 --> Done
C1 --> Done
A2 --> Done
B2 --> Done

Diagram sources

• content-moderation.controller.ts

Section sources

• content-moderation.controller.ts

Best-Effort Handling for Concurrent Operations

The controller wraps state-changing operations in a best-effort pattern to tolerate idempotent failures (e.g., already banned, not banned, already shadow banned, not shadow banned). Non-idempotent errors are rethrown.

flowchart TD
Enter(["tryBestEffort(handler)"]) --> TryOp["Execute handler()"]
TryOp --> Catch{"Error thrown?"}
Catch --> |No| Ok["Return success"]
Catch --> |Yes| Check{"HttpError?<br/>Message contains ignored fragments?"}
Check --> |Yes| Ignore["Suppress error (best-effort)"]
Check --> |No| Rethrow["Rethrow error"]
Ok --> Exit(["Exit"])
Ignore --> Exit
Rethrow --> Exit

Diagram sources

• content-moderation.controller.ts

Section sources

• content-moderation.controller.ts

Administrative Controls

Admin actions:

• Ban/unban posts and comments.
• Shadow ban/unban posts.
• Resolve or ignore reports upon moderation actions.
• Block/unblock users or apply suspensions with end dates.

sequenceDiagram
participant Admin as "Admin UI"
participant API as "Web API"
participant Ctrl as "Controller"
participant Svc as "Service"
Admin->>API : updateContentModerationState(type, id, state)
API->>Ctrl : upsertPostState/upsertCommentState
Ctrl->>Svc : moderateContent(...)
Svc-->>Ctrl : Result
Ctrl-->>API : OK
API-->>Admin : Success
Admin->>API : updateSingleReportStatus(reportId, status)
API-->>Admin : Success

Diagram sources

• ReportPost.tsx
• content-moderation.controller.ts
• content-moderation.service.ts

Section sources

• ReportPost.tsx
• content-moderation.controller.ts

Technical Implementation: State Persistence

• Posts:
  • Flags persisted in the posts table: isBanned and isShadowBanned.
• Users:
  • Flags persisted in the auth table: banned, banReason, banExpires.
  • Suspension data mapped to user adapter for moderation queries.

erDiagram
POSTS {
uuid id PK
boolean isBanned
boolean isShadowBanned
}
AUTH {
text id PK
boolean banned
text banReason
timestamp banExpires
}
PLATFORM_USER {
uuid id PK
text auth_id FK
}
PLATFORM_USER ||--|| AUTH : "authId -> id"

Diagram sources

• post.table.ts
• auth.table.ts

Section sources

• post.table.ts
• auth.table.ts
• user.adapter.ts

Real-Time Propagation to Clients

• Web utilities and API wrappers coordinate moderation-aware behavior on the client side.
• Admin actions trigger backend updates; clients consume updated moderation states through API responses and UI refresh.

Section sources

• moderation.ts
• moderation.ts

Dependency Analysis

Moderation components depend on:

• Controllers depend on services for state transitions.
• Services depend on adapters and database tables for persistence.
• Admin UI depends on web API wrappers to invoke moderation endpoints.

graph LR
RP["ReportPost.tsx"] --> MC["content-moderation.controller.ts"]
MC --> MS["content-moderation.service.ts"]
MS --> PT["post.table.ts"]
MS --> UA["user.adapter.ts"]
UA --> AT["auth.table.ts"]
MU["moderation.ts (utils)"] --> MA["moderation.ts (api)"]
MA --> MC

Diagram sources

• ReportPost.tsx
• content-moderation.controller.ts
• content-moderation.service.ts
• post.table.ts
• user.adapter.ts
• auth.table.ts
• moderation.ts
• moderation.ts

Section sources

• content-moderation.controller.ts
• content-moderation.service.ts
• post.table.ts
• auth.table.ts
• user.adapter.ts
• ReportPost.tsx
• moderation.ts
• moderation.ts

Performance Considerations

• Idempotency: Best-effort pattern reduces retries on redundant operations.
• Indexing: Post visibility index supports efficient filtering by moderation flags.
• Batch updates: Group related report resolutions with state changes to minimize round-trips.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common scenarios:

• Attempting to unban or shadow-unban when already in desired state:
  • Controller suppresses errors via best-effort handling.
• Attempting to ban or shadow-ban when already in that state:
  • Controller suppresses errors via best-effort handling.
• Invalid state transitions:
  • Validation schemas reject unsupported values.

Resolution steps:

• Verify state values match supported enums.
• Retry operations if transient failures occur.
• Confirm database updates for flags and related report resolutions.

Section sources

• content-moderation.schema.ts
• content-moderation.controller.ts
• content-moderation.service.ts

Conclusion

The moderation system defines clear content states with distinct visibility and reporting implications. Controllers enforce safe, idempotent transitions, services persist changes to the database, and admin tools streamline manual interventions. Together, these components ensure platform safety, predictable user experiences, and operational resilience.