# 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.**