Comprehensive workflow guide with automated testing - Last updated: 2025-09-28
Table of Contents#
- Quick Start
- Content Moderation Workflows
- Filter Management
- User Reputation Management
- Review Queue Operations
- Integration Patterns
- 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#
# 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:
Moderation service listening on port 8080
✅ Database connected
✅ Redis connected
✅ All filters initialized
2. Health Check Verification#
# Test service health
curl http://localhost:8080/health
Expected Response:
{
"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
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:
{
"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
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:
{
"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
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
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
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
curl http://localhost:8080/v1/filters
Expected Response:
{
"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
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
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
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
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
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
curl http://localhost:8080/v1/users/new_user_123/reputation
Expected Response:
{
"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
# 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
curl "http://localhost:8080/v1/users/test_user/history?limit=10"
Expected Response:
{
"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
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
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
curl http://localhost:8080/v1/queue
Expected Response:
{
"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
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:
// 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#
// 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:
# 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:
# 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:
# 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#
# 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.