telegram-management-system/marketing-agent/services/safety-guard/README.md

Safety Guard Service

Content moderation, compliance checking, and rate limiting service for the Marketing Intelligence Agent system.

Overview

The Safety Guard service provides comprehensive safety and compliance features:

• Content Moderation: AI-powered content analysis with profanity detection, sentiment analysis, and toxicity checking
• Compliance Management: Region-specific compliance validation (GDPR, CCPA, etc.)
• Rate Limiting: Flexible rate limiting with tier-based controls
• Content Policy: Customizable content policies with pattern matching and validation rules

Features

Content Moderation

• Multi-layer moderation using OpenAI, Google Cloud NLP, and local filters
• Profanity detection with custom word lists
• Sentiment analysis and toxicity scoring
• Risk score calculation and content categorization
• Result caching for performance optimization

Compliance Checking

• Region-specific compliance rules (EU/GDPR, CA/CCPA, BR/LGPD, ZA/POPIA)
• Consent validation and tracking
• Age restriction enforcement
• Data retention policy validation
• Marketing-specific compliance (opt-out requirements, double opt-in)

Rate Limiting

• Hierarchical rate limits (per second, minute, hour, day)
• Tier-based limits (free, basic, pro, enterprise)
• Custom rate limit creation
• Violation tracking and reporting
• Redis-based distributed rate limiting

Content Policy

• Configurable content policies (default, strict, marketing)
• Pattern-based content validation
• Media size and type restrictions
• Link validation and spam detection
• Policy violation logging and reporting

API Endpoints

Content Moderation

• POST /api/v1/moderate - Moderate single content
• POST /api/v1/moderate/bulk - Moderate multiple contents

Compliance

• POST /api/v1/compliance/check - Check compliance for action
• POST /api/v1/compliance/consent/validate - Validate user consent
• GET /api/v1/compliance/report - Get compliance report

Rate Limiting

• POST /api/v1/ratelimit/check - Check rate limit
• POST /api/v1/ratelimit/check-multiple - Check multiple limits
• GET /api/v1/ratelimit/status - Get rate limit status
• POST /api/v1/ratelimit/reset - Reset rate limit
• GET /api/v1/ratelimit/violations - Get violation report

Content Policy

• POST /api/v1/policy/validate - Validate content against policy
• PUT /api/v1/policy/{policyId} - Update policy
• GET /api/v1/policy/violations - Get policy violation report

Combined Safety Check

• POST /api/v1/safety/check - Comprehensive safety validation

Installation

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start the service
npm start

# Development mode with auto-reload
npm run dev

Configuration

Environment Variables

• PORT: Service port (default: 3004)
• MONGODB_URI: MongoDB connection string
• REDIS_HOST/PORT: Redis connection details
• OPENAI_API_KEY: OpenAI API key for AI moderation
• GOOGLE_CLOUD_PROJECT: Google Cloud project for NLP API
• CUSTOM_BAD_WORDS: Comma-separated custom bad words

Rate Limit Configuration

Default rate limits can be adjusted in the service initialization:

// Message rate limits
'message:minute': 30 points
'message:hour': 500 points
'message:day': 5000 points

// API rate limits
'api:request:second': 10 points
'api:request:minute': 100 points

Compliance Regions

Supported regions with specific compliance rules:

• EU: GDPR compliance
• CA: CCPA compliance
• BR: LGPD compliance
• ZA: POPIA compliance
• DEFAULT: General compliance

Usage Examples

Content Moderation

// Moderate content
const response = await fetch('http://localhost:3004/api/v1/moderate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        content: 'Hello world!',
        contentType: 'text'
    })
});

const result = await response.json();
// result.data.approved: true/false
// result.data.riskScore: 0-1
// result.data.violations: [...]

Compliance Check

// Check compliance
const response = await fetch('http://localhost:3004/api/v1/compliance/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        action: 'bulk_message',
        content: 'Marketing message',
        targetRegion: 'EU',
        targetAudience: { minAge: 16 },
        metadata: { hasConsent: true }
    })
});

Rate Limit Check

// Check rate limit
const response = await fetch('http://localhost:3004/api/v1/ratelimit/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        limitType: 'message:hour',
        identifier: 'user123',
        tier: 'pro',
        cost: 1
    })
});

Combined Safety Check

// Comprehensive safety check
const response = await fetch('http://localhost:3004/api/v1/safety/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        content: 'Check out this offer!',
        action: 'message',
        context: {
            accountId: 'account123',
            targetRegion: 'EU',
            targetAudience: { minAge: 18 },
            tier: 'pro',
            policyId: 'marketing'
        }
    })
});

Development

Running Tests

npm test

Adding Custom Moderation Rules

1. Add custom bad words in .env:

   CUSTOM_BAD_WORDS=word1,word2,word3
   

2. Create custom content policy:

   await contentPolicyService.updatePolicy('custom', {
       rules: {
           prohibitedPatterns: ['pattern1', 'pattern2'],
           maxRiskScore: 0.5
       }
   });
   

3. Add custom rate limits:

   await rateLimiterService.setCustomRateLimit('special-campaign', {
       points: 1000,
       duration: 3600,
       blockDuration: 300
   });
   

Monitoring

Health Check

curl http://localhost:3004/health

Metrics

• Moderation processing time
• Compliance check results
• Rate limit violations
• Policy violation trends

Security Considerations

1. API Keys: Store securely in environment variables
2. Rate Limiting: Protect against abuse
3. Content Storage: Limited content preview storage for privacy
4. TTL Indexes: Automatic cleanup of old violation records
5. Fail-Open: Service fails permissively on errors to avoid blocking

License

Proprietary