# 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

## 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`

## 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