🏗️ CORE ARCHITECTURE & DESIGN PHILOSOPHY CHEAT SHEET #

# Red 3.5+ Compliant Cog Structure
from redbot.core import commands, Config
import asyncio
import logging

log = logging.getLogger("red.mycog")

# REQUIRED: GDPR Compliance Statement
__red_end_user_data_statement__ = (
    "This cog stores user IDs and guild IDs for configuration purposes. "
    "No personal data is stored."
)

class MyCog(commands.Cog):
    """Modern Red 3.5+ cog implementation"""
    
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(
            self, 
            identifier=1234567890,
            force_registration=True  # RED 3.5+ BEST PRACTICE
        )
        self.background_tasks = []
        
        # Register defaults with structured data
        self.config.register_guild(
            enabled=True,
            settings={"feature": False}
        )
    
    async def cog_load(self):
        """Called after __init__ when cog is loaded"""
        log.info("Cog loading...")
        await self.start_background_tasks()
    
    async def cog_unload(self):
        """Called before cog removal - CRITICAL for cleanup"""
        log.info("Cog unloading...")
        for task in self.background_tasks:
            if not task.done():
                task.cancel()
        if self.background_tasks:
            await asyncio.gather(*self.background_tasks, return_exceptions=True)
    
    async def red_delete_data_for_user(self, kwargs):
        """REQUIRED: GDPR compliance data deletion"""
        user_id = kwargs.get("user_id")
        if user_id:
            await self.config.user_from_id(user_id).clear()

# REQUIRED: Async setup function (Red 3.5+)
async def setup(bot):
    """Called by Red when loading the cog - MUST BE ASYNC"""
    cog = MyCog(bot)
    await bot.add_cog(cog)  # add_cog is async in Red 3.5+

# Context Abstraction Pattern
class RichContext:
    """Enhanced context with Red-specific utilities"""
    
    async def tick(self, success=True):
        """Visual confirmation with emoji reactions"""
        emoji = "✅" if success else "❌"
        try:
            await self.message.add_reaction(emoji)
        except discord.HTTPException:
            await self.send(emoji)
    
    async def maybe_send_embed(self, embed):
        """Intelligent embed sending with fallback"""
        if self.channel.permissions_for(self.me).embed_links:
            await self.send(embed=embed)
        else:
            await self.send(embed.description or "No content")

# Error Boundary Implementation
async def cog_command_error(self, ctx, error):
    """Cog-level error handling boundary"""
    if isinstance(error, commands.UserInputError):
        await ctx.send_help(ctx.command)
    elif isinstance(error, commands.CheckFailure):
        await ctx.send("Permission denied")
    else:
        log.exception(f"Unexpected error in {ctx.command}: {error}")

# Instance Structure
/home/user/.local/share/Red-DiscordBot/
├── instance1/                    # First bot instance
│   ├── config.json              # Instance configuration
│   ├── cogs/                    # Instance-specific cogs
│   ├── data/                    # Isolated data storage
│   └── logs/                    # Instance logs
├── instance2/                    # Second bot instance  
│   ├── config.json              # Separate configuration
│   ├── cogs/                    # Independent cog storage
│   ├── data/                    # Isolated data
│   └── logs/                    # Separate logs
└── global_cogs/                  # Shared cog repository
    ├── economy/                 # Shared cog code
    ├── moderation/              # Reusable across instances
    └── music/                   # Common functionality

# Instance Lifecycle Management
redbot-setup                      # Interactive instance creation
redbot-setup --no-prompt         # Automated instance setup
redbot <instance_name>            # Run specific instance
redbot <instance_name> --edit     # Edit instance configuration

# Multi-Instance Operations
redbot-launcher                   # GUI launcher for multiple instances
redbot --list                     # List all instances
redbot --delete <instance>        # Remove instance safely

# Modern Config Setup (Red 3.5+)
class AdvancedCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(
            self,
            identifier=1234567890,
            force_registration=True  # PREVENTS SILENT FAILURES
        )
        
        # Structured Default Registration
        default_global = {
            "version": "1.0.0",
            "debug": False,
            "api_keys": {}
        }
        
        default_guild = {
            "enabled": True,
            "prefix": "!",
            "modules": {
                "economy": {"enabled": False, "currency": "credits"},
                "moderation": {"enabled": True, "auto_ban": False}
            },
            "channels": {"log": None, "admin": None},
            "roles": {"moderator": [], "admin": []},
            "permissions": {"custom_commands": []}
        }
        
        # Force registration prevents typos and ensures defaults
        self.config.register_global(default_global)
        self.config.register_guild(default_guild)
        
        # Custom scope for complex data
        self.config.custom("ECONOMY_ACCOUNTS").register(
            balance=0,
            transactions=[],
            daily_last=None
        )
    
    # Safe nested data modification
    async def update_user_balance(self, user_id, amount):
        """Thread-safe balance update with context manager"""
        async with self.config.custom("ECONOMY_ACCOUNTS", user_id).all() as data:
            data["balance"] += amount
            data["transactions"].append({
                "amount": amount,
                "timestamp": datetime.utcnow().isoformat(),
                "type": "admin_adjustment"
            })

# Permission Privilege Levels (Ascending Order)
PRIVILEGE_LEVELS = {
    "NONE": 0,           # No special privileges
    "MOD": 1,            # Moderator level
    "ADMIN": 2,          # Administrator level  
    "GUILD_OWNER": 3,    # Guild owner privileges
    "BOT_OWNER": 4       # Bot owner (highest)
}

# Permission Model Implementation
class PermissionManager:
    def __init__(self, bot):
        self.bot = bot
        self.global_perms = GlobalPermissionModel(bot)
        self.guild_perms = GuildPermissionModel(bot)
        self.channel_perms = ChannelPermissionModel(bot)
    
    async def check_permissions(self, ctx, required_level):
        """Hierarchical permission checking"""
        user_level = await self.get_user_privilege_level(ctx)
        
        # Check global whitelist/blacklist first
        if await self.global_perms.is_user_blacklisted(ctx.author):
            return False
        if await self.global_perms.is_user_whitelisted(ctx.author):
            return True
            
        # Check guild-specific permissions
        if ctx.guild:
            guild_level = await self.guild_perms.get_user_level(ctx)
            if guild_level >= required_level:
                return True
                
        # Fallback to user privilege level
        return user_level >= required_level

# Permission Decorators
@commands.check_any(
    checks.is_owner(),
    checks.admin_or_permissions(manage_guild=True),
    checks.has_role("Administrator")
)
async def admin_command(self, ctx):
    """Multi-layer permission checking"""
    await ctx.send("Admin command executed")

# Command Type Evolution
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Command       │    │      Group       │    │  HybridCommand  │
│   (Basic)       │    │   (Container)    │    │ (Slash + Text)  │
├─────────────────┤    ├──────────────────┤    ├─────────────────┤
│ • Single action │    │ • Sub-commands   │    │ • Modern syntax │
│ • Simple args   │    │ • Organization   │    │ • Dual support  │
│ • Text only     │    │ • Hierarchical   │    │ • Future-proof  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

# Advanced Command Implementation
class ModernCog(commands.Cog):
    @commands.hybrid_command()  # Red 3.5+ hybrid commands
    @app_commands.describe(user="User to check")
    async def profile(self, ctx, user: discord.Member = None):
        """Get user profile (works as slash and text command)"""
        user = user or ctx.author
        
        # Rich context usage
        embed = discord.Embed(
            title=f"{user.display_name}'s Profile",
            color=await ctx.embed_color()  # Theme-aware color
        )
        
        # Visual confirmation
        await ctx.tick()  # ✅ reaction
        await ctx.send(embed=embed)
    
    @commands.group(invoke_without_command=True)
    async def config(self, ctx):
        """Configuration command group"""
        if ctx.invoked_subcommand is None:
            await ctx.send_help(ctx.command)
    
    @config.command()
    @commands.admin_or_permissions(manage_guild=True)
    @commands.cooldown(1, 30, commands.BucketType.guild)
    async def toggle(self, ctx, *, feature: str):
        """Toggle a configuration feature"""
        async with self.config.guild(ctx.guild).features() as features:
            features[feature] = not features.get(feature, False)
        
        status = "enabled" if features[feature] else "disabled"
        await ctx.send(f"Feature `{feature}` {status}")

# Built-in Converter Ecosystem
BUILT_IN_CONVERTERS = {
    # Discord Objects
    "discord.Member": "User in current guild",
    "discord.User": "Any Discord user", 
    "discord.TextChannel": "Text channel",
    "discord.Role": "Guild role",
    "discord.Emoji": "Custom emoji",
    
    # Utility Converters  
    "commands.Greedy": "Multiple arguments",
    "typing.Union": "Multiple type options",
    "typing.Optional": "Optional argument",
    
    # Red-specific
    "redbot.core.commands.Context": "Enhanced context",
    "redbot.core.utils.chat_formatting.TimedeltaConverter": "Time spans"
}

# Custom Converter Example
class ConfigKeyConverter(commands.Converter):
    """Converter for configuration keys with validation"""
    
    async def convert(self, ctx, argument):
        valid_keys = await ctx.cog.config.guild(ctx.guild).all()
        if argument not in valid_keys:
            raise commands.BadArgument(
                f"Invalid config key. Valid keys: {', '.join(valid_keys)}"
            )
        return argument

# AutoShardedBot Inheritance Chain
discord.AutoShardedBot → commands.AutoShardedBot → Red (Bot Class)

class RedBot(commands.AutoShardedBot):
    """Red's enhanced autosharded bot implementation"""
    
    def __init__(self, *args, kwargs):
        super().__init__(*args, kwargs)
        self.uptime = datetime.utcnow()
        self.counter = Counter()
        self._config = None
        self._disabled_commands = []
        
    async def on_shard_connect(self, shard_id):
        """Called when a shard connects"""
        log.info(f"Shard {shard_id} connected")
        
    async def on_shard_disconnect(self, shard_id):
        """Called when a shard disconnects"""
        log.warning(f"Shard {shard_id} disconnected")
        
    async def on_shard_ready(self, shard_id):
        """Called when a shard is ready"""
        log.info(f"Shard {shard_id} ready")
        await self.update_shard_stats(shard_id)

# Shard Health Monitoring
async def monitor_shard_health(bot):
    """Monitor and report shard health"""
    while True:
        unhealthy_shards = []
        for shard_id, shard in bot.shards.items():
            if shard.latency > 1.0:  # High latency
                unhealthy_shards.append(shard_id)
            
        if unhealthy_shards:
            log.warning(f"Unhealthy shards detected: {unhealthy_shards}")
            
        await asyncio.sleep(60)  # Check every minute

# Lock Hierarchy (Fine to Coarse)
Per-Value Lock → Per-Group Lock → Per-Scope Lock → Global Lock

# Practical Lock Implementation
class ThreadSafeConfigManager:
    def __init__(self, config):
        self.config = config
        self._locks = {}
        
    async def safe_increment(self, user_id):
        """Thread-safe counter increment"""
        lock_key = f"user_{user_id}_counter"
        
        # Get or create lock for this specific value
        if lock_key not in self._locks:
            self._locks[lock_key] = asyncio.Lock()
            
        async with self._locks[lock_key]:
            current = await self.config.user_from_id(user_id).counter()
            new_value = current + 1
            await self.config.user_from_id(user_id).counter.set(new_value)
            return new_value
    
    async def bulk_update_guild_data(self, guild_id, updates):
        """Thread-safe bulk data update"""
        async with self.config.guild_from_id(guild_id).all() as guild_data:
            for key, value in updates.items():
                guild_data[key] = value
            # Automatic commit on context exit
            
# Deadlock Prevention Pattern
async def safe_multi_lock_operation(config, user_id1, user_id2):
    """Prevent deadlocks with ordered locking"""
    # Always acquire locks in consistent order (by ID)
    ids = sorted([user_id1, user_id2])
    
    async with config.user_from_id(ids[0]).balance.get_lock():
        async with config.user_from_id(ids[1]).balance.get_lock():
            # Perform operations safely
            balance1 = await config.user_from_id(ids[0]).balance()
            balance2 = await config.user_from_id(ids[1]).balance()
            
            # Transfer between users safely
            await config.user_from_id(ids[0]).balance.set(balance1 - 100)
            await config.user_from_id(ids[1]).balance.set(balance2 + 100)

# Lock Timeout Handling
async def safe_config_operation(config, timeout=5.0):
    """Config operation with timeout protection"""
    try:
        async with asyncio.wait_for(
            config.guild(guild).settings.get_lock(),
            timeout=timeout
        ):
            # Perform operation
            settings = await config.guild(guild).settings()
            settings["last_updated"] = datetime.utcnow()
            await config.guild(guild).settings.set(settings)
            
    except asyncio.TimeoutError:
        log.warning("Config operation timed out")
        return False
    return True

# Resource Cleanup Pattern
class ResourceManagedCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.active_locks = WeakSet()
        
    async def cog_unload(self):
        """Ensure all locks are released on unload"""
        for lock in list(self.active_locks):
            if lock.locked():
                lock.release()
        self.active_locks.clear()

# ConfigMeta Implementation Details
class ConfigMeta(type):
    """Metaclass ensuring singleton config per cog/identifier"""
    
    _instances = {}  # Global registry of config instances
    
    def __call__(cls, cog_instance, identifier, kwargs):
        # Create unique key for cog instance + identifier
        key = (id(cog_instance), identifier)
        
        if key not in cls._instances:
            # Create new instance if not exists
            instance = super().__call__(cog_instance, identifier, kwargs)
            cls._instances[key] = instance
            log.debug(f"Created new config instance: {key}")
        else:
            log.debug(f"Reusing existing config instance: {key}")
            
        return cls._instances[key]
    
    @classmethod
    def cleanup_instance(cls, cog_instance, identifier):
        """Clean up config instance when cog unloads"""
        key = (id(cog_instance), identifier)
        if key in cls._instances:
            del cls._instances[key]
            log.debug(f"Cleaned up config instance: {key}")

# Config Class with Singleton Pattern
class Config(metaclass=ConfigMeta):
    """Configuration manager with singleton enforcement"""
    
    def __init__(self, cog_instance, identifier, kwargs):
        self.cog_instance = cog_instance
        self.identifier = identifier
        self._driver = None
        self._defaults = {}
        
    @classmethod
    def get_conf(cls, cog_instance, identifier, kwargs):
        """Primary entry point - enforces singleton pattern"""
        return cls(cog_instance, identifier, kwargs)
        
    def __del__(self):
        """Cleanup on garbage collection"""
        if hasattr(self, 'cog_instance') and hasattr(self, 'identifier'):
            ConfigMeta.cleanup_instance(self.cog_instance, self.identifier)

# Usage Pattern Ensuring Singleton
class MyCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        # This will always return the same instance for this cog
        self.config = Config.get_conf(self, identifier=12345)
        
    async def cog_unload(self):
        """Singleton cleanup on cog unload"""
        ConfigMeta.cleanup_instance(self, 12345)

# Debug and Monitoring Tools
class ConfigInstanceMonitor:
    @staticmethod
    def get_active_instances():
        """Get all active config instances"""
        return list(ConfigMeta._instances.keys())
    
    @staticmethod
    def get_instance_count():
        """Get total number of active instances"""
        return len(ConfigMeta._instances)
    
    @staticmethod  
    def detect_leaked_instances():
        """Detect potentially leaked config instances"""
        leaked = []
        for (cog_id, identifier), instance in ConfigMeta._instances.items():
            # Check if cog instance still exists
            if not hasattr(instance, 'cog_instance') or instance.cog_instance is None:
                leaked.append((cog_id, identifier))
        return leaked

# Complete Modern Cog Template (Production-Ready)
from redbot.core import commands, Config, checks
import asyncio
import logging

log = logging.getLogger("red.mycog")

# REQUIRED: GDPR compliance statement
__red_end_user_data_statement__ = (
    "This cog stores user IDs and guild IDs for configuration purposes. "
    "No personal data is stored."
)

class ProductionCog(commands.Cog):
    """Production-ready cog with all best practices"""
    
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(
            self, 
            identifier=1234567890,
            force_registration=True  # RED 3.5+ BEST PRACTICE
        )
        
        # Structured defaults
        self.config.register_global(version="1.0.0", enabled=True)
        self.config.register_guild(
            enabled=True,
            settings={"feature": False},
            channels={"log": None}
        )
        
        self.background_tasks = []
        
    async def cog_load(self):
        """Initialize after cog loading"""
        log.info("ProductionCog loading...")
        await self.start_background_tasks()
        
    async def cog_unload(self):
        """Cleanup before cog removal"""
        log.info("ProductionCog unloading...")
        for task in self.background_tasks:
            if not task.done():
                task.cancel()
        if self.background_tasks:
            await asyncio.gather(*self.background_tasks, return_exceptions=True)
            
    async def red_delete_data_for_user(self, kwargs):
        """REQUIRED: GDPR data deletion"""
        user_id = kwargs.get("user_id")
        if user_id:
            await self.config.user_from_id(user_id).clear()
    
    @commands.hybrid_command()  # Modern hybrid command
    async def hello(self, ctx):
        """Say hello (works as slash and text command)"""
        await ctx.tick()  # Visual confirmation
        await ctx.send("Hello!")

# REQUIRED: Async setup function
async def setup(bot):
    """Load the cog - MUST BE ASYNC in Red 3.5+"""
    cog = ProductionCog(bot)
    await bot.add_cog(cog)  # add_cog is async

# Instance Management Commands
redbot-setup                      # Create new instance
redbot <instance>                 # Run instance
redbot <instance> --edit          # Edit instance config

# Essential CLI Commands  
[p]load cogname                   # Load cog
[p]unload cogname                 # Unload cog
[p]reload cogname                 # Reload cog (hot reload)
[p]cogs                          # List all cogs

# Config Scope Quick Reference
GLOBAL = 0     # await config.setting()
GUILD = 1      # await config.guild(guild).setting()
CHANNEL = 2    # await config.channel(channel).setting()  
ROLE = 3       # await config.role(role).setting()
USER = 4       # await config.user(user).setting()
MEMBER = 5     # await config.member(member).setting()
CUSTOM = 6     # await config.custom("SCOPE", id).setting()