GuardDen/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

GuardDen is a Discord moderation bot built with discord.py, PostgreSQL, and optional AI integration (Claude/OpenAI). Self-hosted with Docker support.

Commands

# Install dependencies
pip install -e ".[dev,ai]"

# Run the bot
python -m guardden

# Run tests
pytest

# Run single test
pytest tests/test_verification.py::TestVerificationService::test_verify_correct

# Lint and format
ruff check src tests
ruff format src tests

# Type checking
mypy src

# Docker deployment
docker compose up -d

Architecture

• src/guardden/bot.py - Main bot class (GuardDen) extending commands.Bot, manages lifecycle and services
• src/guardden/config.py - Pydantic settings loaded from environment variables (prefix: GUARDDEN_)
• src/guardden/models/ - SQLAlchemy 2.0 async models for PostgreSQL
• src/guardden/services/ - Business logic (database, guild config, automod, AI, verification, rate limiting)
• src/guardden/cogs/ - Discord command groups (events, moderation, admin, automod, ai_moderation, verification)

Key Patterns

• All database operations use async SQLAlchemy with asyncpg
• Guild configurations are cached in GuildConfigService._cache
• Discord snowflake IDs stored as BigInteger in PostgreSQL
• Moderation actions logged to ModerationLog table with automatic strike escalation
• Environment variables: GUARDDEN_DISCORD_TOKEN, GUARDDEN_DATABASE_URL

Automod System

• AutomodService in services/automod.py handles rule-based content filtering
• Checks run in order: banned words → scam links → spam → invite links
• Spam tracking uses per-guild, per-user trackers with automatic cleanup
• Scam detection uses compiled regex patterns in SCAM_PATTERNS list
• Results return AutomodResult dataclass with actions to take
• Whitelist: Users in GuildSettings.whitelisted_user_ids bypass ALL automod checks
• Users with "Manage Messages" permission also bypass automod

AI Moderation System

• services/ai/ contains provider abstraction and implementations
• AIProvider base class defines interface: moderate_text(), analyze_image(), analyze_phishing()
• AnthropicProvider and OpenAIProvider implement the interface
• NullProvider used when AI is disabled (returns empty results)
• Factory pattern via create_ai_provider(provider, api_key)
• ModerationResult includes severity scoring based on confidence + category weights
• Sensitivity setting (0-100) adjusts thresholds per guild
• NSFW-Only Filtering (default: True): When enabled, only sexual content is filtered; violence, harassment, etc. are allowed
• Filtering controlled by nsfw_only_filtering field in GuildSettings
• Whitelist: Users in GuildSettings.whitelisted_user_ids bypass ALL AI moderation checks

Verification System

• VerificationService in services/verification.py manages challenges
• Challenge types: button, captcha, math, emoji (via ChallengeGenerator classes)
• PendingVerification tracks user challenges with expiry and attempt limits
• Discord UI components in cogs/verification.py: VerifyButton, EmojiButton, CaptchaModal
• Background task cleans up expired verifications every 5 minutes

Rate Limiting System

• RateLimiter in services/ratelimit.py provides general-purpose rate limiting
• Scopes: USER (global), MEMBER (per-guild), CHANNEL, GUILD
• @ratelimit() decorator for easy command rate limiting
• get_rate_limiter() returns singleton instance
• Default limits configured for commands, moderation, verification, messages

Notification System

• utils/notifications.py contains send_moderation_notification() utility
• Handles sending moderation warnings to users with DM → in-channel fallback
• In-Channel Warnings (default: False): Optional PUBLIC channel messages when DMs fail
• IMPORTANT: In-channel messages are PUBLIC, visible to all users (Discord API limitation)
• Temporary messages auto-delete after 10 seconds to minimize clutter
• Used by automod, AI moderation, and manual moderation commands
• Controlled by send_in_channel_warnings field in GuildSettings
• Disabled by default for privacy reasons

Adding New Cogs

1. Create file in src/guardden/cogs/
2. Implement setup(bot) async function
3. Add cog path to _load_cogs() in bot.py

Adding New AI Provider

1. Create src/guardden/services/ai/newprovider.py
2. Implement AIProvider abstract class
3. Add to factory in services/ai/factory.py
4. Add config option in config.py

Adding New Challenge Type

1. Create new ChallengeGenerator subclass in services/verification.py
2. Add to ChallengeType enum
3. Register in VerificationService._generators
4. Create corresponding UI components in cogs/verification.py if needed