sojorn/sojorn_docs/USER_APPEAL_SYSTEM.md

User Appeal System - Comprehensive Guide

🎯 Overview

A nuanced violation and appeal system that prioritizes content moderation over immediate bans. Users get multiple chances with clear progression from warnings to suspensions to bans.

📊 Violation Tiers

🚫 Hard Violations (No Appeal)

• Racial slurs, hate speech, explicit threats
• Illegal content, CSAM, terrorism
• Immediate content deletion
• Account status change: warning → suspended → banned
• No appeal option

⚠️ Soft Violations (Appealable)

• Borderline content, gray areas
• Context-dependent issues
• Content hidden pending moderation
• User can appeal with explanation
• Monthly appeal limits apply

🔄 Violation Progression

Account Status Levels

1. 🟢 Active - Normal user status
2. 🟡 Warning - First serious violation
3. 🟠 Suspended - Multiple violations
4. 🔴 Banned - Too many violations

Thresholds (30-day window)

• 1 Hard Violation → Warning
• 2 Hard Violations → Suspended
• 3 Hard Violations → Banned
• 3 Total Violations → Warning
• 5 Total Violations → Suspended
• 8 Total Violations → Banned

🛡️ Content Handling

Hard Violations

• ✅ Content deleted immediately
• ✅ Posts/comments removed
• ✅ User notified of account status change
• ✅ Violation recorded in history

Soft Violations

• ✅ Content hidden (status: pending_moderation)
• ✅ User can appeal within 72 hours
• ✅ 3 appeals per month limit
• ✅ Content restored if appeal approved

📋 User Interface

In User Settings

• 📊 Violation Summary - Total counts, current status
• 📜 Violation History - Detailed list of all violations
• 🚩 Appeal Options - For appealable violations
• ⏰ Appeal Deadlines - Clear time limits
• 📈 Progress Tracking - See account status progression

Appeal Process

1. User submits appeal with reason (10-1000 chars)
2. Optional context and evidence URLs
3. Admin reviews within 24-48 hours
4. Decision: Approved (content restored) or Rejected (content stays hidden)

🔧 API Endpoints

User Endpoints

GET  /api/v1/appeals                    - Get user violations
GET  /api/v1/appeals/summary           - Get violation summary  
POST /api/v1/appeals                    - Create appeal
GET  /api/v1/appeals/:id                - Get appeal details

Admin Endpoints

GET  /api/v1/admin/appeals/pending       - Get pending appeals
PATCH /api/v1/admin/appeals/:id/review   - Review appeal
GET  /api/v1/admin/appeals/stats        - Get appeal statistics

📊 Database Schema

Key Tables

• user_violations - Individual violation records
• user_appeals - Appeal submissions and decisions
• user_violation_history - Daily violation tracking
• appeal_guidelines - Configurable rules

Violation Tracking

• Content deletion status
• Account status changes
• Appeal history
• Progressive penalties

🎛️ Admin Tools

In Directus

• user_violations collection - Review all violations
• user_appeals collection - Manage appeals
• user_violation_history - Track patterns
• appeal_guidelines - Configure rules

Review Workflow

1. See pending appeals in Directus
2. Review violation details and user appeal
3. Approve/Reject with decision reasoning
4. System handles content restoration and status updates

🔄 Appeal Outcomes

Approved Appeal

• ✅ Content restored (if soft violation)
• ✅ Violation marked as "overturned"
• ✅ Account status may improve
• ✅ User notified of decision

Rejected Appeal

• ❌ Content stays hidden/deleted
• ❌ Violation marked as "upheld"
• ❌ Account status may worsen
• ❌ User notified of decision

📈 Analytics & Tracking

Metrics Available

• Violation trends by type and user
• Appeal success rates
• Account status progression
• Content deletion statistics
• Repeat offender patterns

Automated Actions

• Content deletion for hard violations
• Account status updates based on thresholds
• Appeal deadline enforcement
• Monthly appeal limit enforcement

🚀 Benefits

For Users

• Fair treatment with clear progression
• Appeal options for gray areas
• Transparency about violations
• Multiple chances before ban

For Platform

• Reduced moderation burden with automation
• Clear audit trail for all decisions
• Scalable violation management
• Data-driven policy enforcement

🎯 Implementation Status

✅ Fully Deployed

• Database schema created
• API endpoints implemented
• Violation logic active
• Appeal system functional
• Directus integration complete

✅ Ready for Use

• Users can view violations in settings
• Appeals can be submitted and reviewed
• Content automatically managed
• Account status progression active

The system provides a balanced approach that protects the platform while giving users fair opportunities to correct mistakes.