CloudyAPI - Backend API & Database

CloudyAPI is the central backend service for CloudyAI, built with NestJS. It handles guild configurations, moderation logic, message evaluation, and coordinates between all microservices.

🎯 Features

• Guild Configuration Management: Store and retrieve server settings
• Moderation Engine: Evaluate messages and determine sanctions
• Escalation System: Progressive sanctions based on user history
• WebSocket Support: Real-time updates for dashboard
• MongoDB Integration: Persistent storage for configs, logs, and samples
• JWT Authentication: Secure API endpoints

🚀 Quick Start

Installation

cd CloudyAPI
npm install

Configuration

Create .env file:

PORT=3000
MONGODB_URI=mongodb://localhost:27017/cloudydb
JWT_SECRET=your-super-secret-jwt-key-change-this
BOT_API_TOKEN=your-bot-api-token-here

# Microservices
CLOUDYMOD_URL=http://localhost:8001
CLOUDYMOD_API_TOKEN=your-cloudymod-token
CLOUDYTRAD_URL=http://localhost:5001
CLOUDYTRAD_API_TOKEN=your-cloudytrad-token

Running

# Development
npm run start:dev

# Production
npm run build
npm run start:prod

📡 API Endpoints

Moderation

POST /v1/moderation/evaluate

Evaluate a message for violations.

Headers:

Authorization: Bearer your-bot-api-token
Content-Type: application/json

Request:

{
  "guildId": "123456789",
  "channelId": "987654321",
  "messageId": "111222333",
  "userId": "444555666",
  "username": "User#1234",
  "content": "Message text",
  "metadata": {
    "mentions": 0,
    "mentionsEveryone": false,
    "roles": 0,
    "hasLinks": false
  }
}

Response:

{
  "decision": "WARN",
  "violations": [
    {
      "rule": "AI: toxicity",
      "severity": "medium",
      "matched": "score: 0.75"
    }
  ],
  "reason": "Medium-severity violation",
  "confidence": 0.85
}

GET /v1/moderation/config/:guildId

Get guild configuration.

POST /v1/moderation/config/:guildId

Create/update guild configuration.

PATCH /v1/moderation/config/:guildId/language

Update guild language.

Logging

GET /v1/logging/sanctions/:guildId

Get sanctions for a guild.

GET /v1/logging/sanctions/:guildId/:userId

Get sanctions for a specific user.

Health

GET /health

Health check endpoint.

🗄️ Database Schema

GuildConfig

{
  guildId: string;
  language: 'en' | 'fr' | 'es' | 'de';
  moderation: {
    enabled: boolean;
    autoDelete: boolean;
    mode: 'active' | 'shadow';
    filterLinks: boolean;
  };
  ai: {
    enabled: boolean;
    provider: 'cloudymod';
    threshold: number;
  };
  escalation: {
    enabled: boolean;
  };
  rules: Array<{
    name: string;
    type: 'keyword' | 'regex';
    value: string;
    severity: 'low' | 'medium' | 'high';
    active: boolean;
  }>;
}

Log (Sanctions)

{
  guildId: string;
  userId: string;
  action: 'WARN' | 'TIMEOUT' | 'KICK' | 'BAN';
  reason: string;
  messageId: string;
  messageContent: string;
  channelId: string;
  violations: Array<Violation>;
  source: 'automated' | 'manual';
  timestamp: Date;
}

🔧 Moderation Logic

Decision Flow

1. Check Configuration: Return early if guild not configured
2. AI Analysis: Call CloudyMod if AI enabled
3. Custom Rules: Check keyword/regex patterns
4. Spam Detection: Detect rapid-fire, repeat, and character spam
5. Basic Checks: Links, caps abuse, mention spam
6. Escalation: Determine action based on violations + user history

Escalation Tiers

High Severity:

• First offense: KICK
• Repeat offense: BAN

Medium Severity:

• 0-1 offenses: TIMEOUT
• 2-3 offenses: TIMEOUT (longer)
• 4+ offenses: BAN

Low Severity:

• 0-2 offenses: WARN
• 3-4 offenses: TIMEOUT
• 5+ offenses: KICK

🔒 Security

• JWT Authentication: User endpoints require JWT tokens
• Bot API Token: Bot requests require BOT_API_TOKEN
• Service Tokens: Calls to CloudyMod/CloudyTrad include API tokens

📝 Environment Variables

Variable	Description	Required
PORT	Server port	No (default: 3000)
MONGODB_URI	MongoDB connection string	Yes
JWT_SECRET	JWT signing secret	Yes
BOT_API_TOKEN	Bot authentication token	Yes
CLOUDYMOD_URL	CloudyMod service URL	Yes
CLOUDYMOD_API_TOKEN	CloudyMod API token	Yes
CLOUDYTRAD_URL	CloudyTrad service URL	No
CLOUDYTRAD_API_TOKEN	CloudyTrad API token	No

🐛 Troubleshooting

MongoDB connection failed

• Verify MongoDB is running
• Check MONGODB_URI format
• Ensure network connectivity

CloudyMod/CloudyTrad errors

• Verify services are running
• Check API tokens match
• Test service health endpoints

Escalation not working

• Check escalation.enabled in guild config
• Verify logs are being saved to database
• Review past sanctions count