120 lines
4.8 KiB
Markdown
120 lines
4.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|