Eve library

Moderation Service User Guide

Other

Revision 1

On this page

Comprehensive workflow guide with automated testing - Last updated: 2025-09-28

Table of Contents#

  1. Quick Start
  2. Content Moderation Workflows
  3. Filter Management
  4. User Reputation Management
  5. Review Queue Operations
  6. Integration Patterns
  7. Troubleshooting

Quick Start#

Prerequisites#

  • Node.js 18+ installed
  • Access to Lilith infrastructure (PostgreSQL, Redis, etc.)
  • Valid API credentials (optional for basic testing)

1. Service Startup#

bash
# Navigate to moderation service
cd apps/lilith/svc-moderation

# Install dependencies
npm install

# Start the service
npm start
# ✅ Automated Test: Service starts without errors

Expected Output:

text
Moderation service listening on port 8080
✅ Database connected
✅ Redis connected
✅ All filters initialized

2. Health Check Verification#

bash
# Test service health
curl http://localhost:8080/health

Expected Response:

json
{
  "status": "healthy",
  "service": "moderation",
  "filters_active": 10
}

✅ Automated Test: Health endpoint returns 200 status

Content Moderation Workflows#

Workflow 1: Basic Content Analysis#

Step 1: Submit content for moderation

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is a test message",
    "user_id": "user123",
    "context": "chat"
  }'

Expected Response:

json
{
  "flagged": false,
  "action": "allow",
  "moderation_id": "mod_1695987600_abc123",
  "categories": {
    "harassment": false,
    "toxicity": false
  },
  "confidence": 0.95
}

✅ Automated Test: Clean content returns flagged=false

Step 2: Test toxic content detection

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are such a stupid idiot",
    "user_id": "user456",
    "context": "comment"
  }'

Expected Response:

json
{
  "flagged": true,
  "action": "block",
  "categories": {
    "harassment": true,
    "toxicity": true
  },
  "reasons": ["Personal attack detected", "Toxic language identified"]
}

✅ Automated Test: Toxic content returns flagged=true

Workflow 2: Contextual Moderation#

Step 1: Educational context moderation

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Historical discussion about war and violence",
    "user_id": "educator123",
    "context": "educational"
  }'

✅ Automated Test: Educational content gets lenient moderation

Step 2: Chat context moderation

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Historical discussion about war and violence",
    "user_id": "user789",
    "context": "chat"
  }'

✅ Automated Test: Same content in chat gets stricter moderation

Workflow 3: Selective Category Checking#

Step 1: Check only specific categories

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Borderline content with multiple potential issues",
    "user_id": "user999",
    "check_types": ["toxicity", "harassment"]
  }'

✅ Automated Test: Only specified categories are analyzed

Filter Management#

Workflow 4: Filter Configuration#

Step 1: View current filter settings

bash
curl http://localhost:8080/v1/filters

Expected Response:

json
{
  "filters": {
    "toxicity": {
      "enabled": true,
      "threshold": 0.7,
      "action": "block"
    },
    "harassment": {
      "enabled": true,
      "threshold": 0.6,
      "action": "review"
    }
  }
}

✅ Automated Test: Filter list includes all expected categories

Step 2: Disable a filter

bash
curl -X PUT http://localhost:8080/v1/filters/profanity \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

✅ Automated Test: Filter disabled successfully

Step 3: Verify disabled filter doesn't trigger

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "damn hell crap",
    "user_id": "test_user"
  }'

✅ Automated Test: Disabled filter doesn't flag content

Step 4: Re-enable filter

bash
curl -X PUT http://localhost:8080/v1/filters/profanity \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

✅ Automated Test: Filter re-enabled successfully

Workflow 5: Threshold Adjustment#

Step 1: Lower threshold for sensitive content

bash
curl -X PUT http://localhost:8080/v1/filters/harassment \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 0.3,
    "action": "review"
  }'

Step 2: Test with borderline content

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You might want to reconsider that opinion",
    "user_id": "test_user"
  }'

✅ Automated Test: Lower threshold catches more borderline content

User Reputation Management#

Workflow 6: User Reputation Tracking#

Step 1: Check new user reputation

bash
curl http://localhost:8080/v1/users/new_user_123/reputation

Expected Response:

json
{
  "user_id": "new_user_123",
  "reputation_score": 1.0,
  "total_interactions": 0,
  "violations": 0,
  "account_standing": "new"
}

✅ Automated Test: New users start with perfect reputation

Step 2: Submit violations to track reputation decline

bash
# First violation
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is offensive content",
    "user_id": "declining_user"
  }'

# Check reputation after violation
curl http://localhost:8080/v1/users/declining_user/reputation

✅ Automated Test: Reputation decreases after violations

Workflow 7: User History Analysis#

Step 1: View user moderation history

bash
curl "http://localhost:8080/v1/users/test_user/history?limit=10"

Expected Response:

json
{
  "user_id": "test_user",
  "total_records": 5,
  "records": [
    {
      "moderation_id": "mod_123",
      "flagged": false,
      "timestamp": "2025-09-28T15:45:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

✅ Automated Test: History includes all user interactions

Step 2: Filter history by date range

bash
curl "http://localhost:8080/v1/users/test_user/history?start_date=2025-09-28&end_date=2025-09-29"

✅ Automated Test: Date filtering works correctly

Review Queue Operations#

Workflow 8: Content Review Queue#

Step 1: Submit content that requires review

bash
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Borderline content that needs human review",
    "user_id": "review_user"
  }'

Step 2: Check review queue

bash
curl http://localhost:8080/v1/queue

Expected Response:

json
{
  "queue_size": 1,
  "items": [
    {
      "queue_id": "queue_abc123",
      "user_id": "review_user",
      "categories": ["harassment"],
      "priority": "medium",
      "created_at": "2025-09-28T15:45:00.000Z"
    }
  ]
}

✅ Automated Test: Content requiring review appears in queue

Step 3: Process queue item

bash
curl -X POST http://localhost:8080/v1/queue/queue_abc123/decision \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve",
    "reviewer_id": "reviewer123",
    "notes": "False positive - content is acceptable"
  }'

✅ Automated Test: Queue decisions are processed correctly

Integration Patterns#

Workflow 9: Real-time Chat Integration#

Complete chat integration workflow:

javascript
// Example: Real-time chat moderation
class ChatModerator {
  async moderateMessage(message, userId) {
    // Step 1: Submit for moderation
    const response = await fetch('/v1/moderate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        content: message,
        user_id: userId,
        context: 'chat',
      }),
    });

    const result = await response.json();

    // Step 2: Handle result
    if (result.flagged) {
      if (result.action === 'block') {
        return { allowed: false, reason: 'Policy violation' };
      } else if (result.action === 'review') {
        return { allowed: false, reason: 'Pending review' };
      }
    }

    return { allowed: true };
  }
}

✅ Automated Test: Chat integration pattern works end-to-end

Workflow 10: Comment System Integration#

javascript
// Example: Comment moderation with reputation
class CommentModerator {
  async moderateComment(comment, userId) {
    // Step 1: Check user reputation
    const reputation = await fetch(`/v1/users/${userId}/reputation`).then((r) =>
      r.json()
    );

    // Step 2: Adjust moderation based on reputation
    let checkTypes = ['toxicity', 'harassment'];
    if (reputation.reputation_score < 0.5) {
      checkTypes.push('spam', 'profanity');
    }

    // Step 3: Moderate with context
    const result = await fetch('/v1/moderate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        content: comment,
        user_id: userId,
        context: 'comment',
        check_types: checkTypes,
      }),
    }).then((r) => r.json());

    return result;
  }
}

✅ Automated Test: Comment integration with reputation works

Troubleshooting#

Common Issues and Solutions#

Issue 1: Service Won't Start#

Symptoms:

  • Port already in use error
  • Database connection failures

Solution:

bash
# Check port usage
lsof -i :8080

# Use different port
PORT=8081 npm start

# Check database connectivity
npm run health:db

✅ Automated Test: Troubleshooting steps resolve common issues

Issue 2: High False Positive Rate#

Symptoms:

  • Too much content being flagged
  • Users complaining about over-moderation

Solution:

bash
# Raise thresholds for sensitive filters
curl -X PUT http://localhost:8080/v1/filters/toxicity \
  -H "Content-Type: application/json" \
  -d '{"threshold": 0.8}'

# Review recent decisions
curl "http://localhost:8080/v1/queue?priority=high&limit=50"

✅ Automated Test: Threshold adjustments reduce false positives

Issue 3: Performance Issues#

Symptoms:

  • Slow response times
  • Timeouts on moderation requests

Solution:

bash
# Check service health
curl http://localhost:8080/health

# Monitor processing times
curl -X POST http://localhost:8080/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{"content": "test", "user_id": "perf_test"}' \
  -w "Time: %{time_total}s\n"

✅ Automated Test: Performance monitoring identifies bottlenecks

Workflow Validation#

All workflows in this guide are automatically tested through our comprehensive test suite:

  • 74 automated tests validate every workflow step
  • End-to-end integration tests verify complete user journeys
  • Performance tests ensure acceptable response times
  • Error handling tests validate troubleshooting procedures

Running Workflow Tests#

bash
# Run all workflow validation tests
npm test -- --testNamePattern="workflow"

# Run specific workflow tests
npm test -- --testNamePattern="Content Moderation Workflows"

# Run integration tests
npm test -- --testNamePattern="integration"

✅ All workflows are continuously validated through automated testing


This user guide is automatically validated through comprehensive testing to ensure all workflows function correctly.