Architecture Overview

Ui-Py Architecture Overview

This document explains the architecture and structure of the Ui-Py Discord bot, helping developers understand how the various components work together.

High-Level Overview

Ui-Py is built using the discord.py library and follows a modular design pattern. The bot is structured as follows:

Ui-Py/
├── main.py              # Entry point and core bot class
├── functions/           # Command modules organized by category
│   ├── system/          # Core system commands
│   └── tool/            # Utility and feature-specific commands
├── media/               # Static media files
└── Wiki/                # Documentation

Core Components

Main Bot Class (UiPy)

The UiPy class in main.py is the central component that:

1. Initializes the bot with the necessary intents
2. Sets up an HTTP session for web requests
3. Dynamically loads command modules
4. Handles events like connecting to Discord and shutting down

The bot uses commands.AutoShardedBot from discord.py, which automatically manages sharding for larger bot installations.

Extension System

Commands are organized as extensions (cogs) in the functions/ directory, categorized by their purpose:

• functions/system/ - Core functionality and admin commands
• functions/tool/ - User-facing features and utilities

Each extension follows a standard structure:

1. A class that inherits from commands.Cog
2. Command methods decorated with @app_commands.command()
3. A setup function that registers the cog with the bot

Example:

from discord.ext import commands
from discord import app_commands, Interaction
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from main import UiPy

class MyCog(commands.Cog):
    def __init__(self, bot: "UiPy"):
        self.bot = bot

    @app_commands.command(
        name="mycommand",
        description="Description of my command"
    )
    async def my_command(self, interaction: Interaction):
        await interaction.response.send_message("Hello, world!")

async def setup(bot: "UiPy"):
    await bot.add_cog(MyCog(bot))

Command Handling

Ui-Py uses Discord's slash commands system for all user interactions, which provides:

• Better user experience with command auto-completion
• Structured parameter input
• Integrated permission system

Commands are registered with Discord through the sync command, which can sync commands:

• Globally (takes up to an hour to propagate)
• To a specific guild (instant, good for testing)

Event System

The bot also uses the event system from discord.py to respond to various Discord events:

• on_ready: Called when the bot connects to Discord
• on_message: Used by redirect.py to process links in messages

Custom events can be added by implementing the appropriate event handler in a cog.

Dependency Management

Dependencies are managed using Pipenv, with:

• Pipfile: Defines required packages
• Pipfile.lock: Ensures consistent installations

Deployment

Ui-Py is designed to be deployed in a Docker container, with:

• Dockerfile: Multi-stage build for smaller images
• docker-compose.yml: Simple orchestration
• deploy-dc.sh: Deployment script

This containerized approach ensures consistent execution across different environments.

Adding New Features

To add a new feature to Ui-Py:

1. Create a new Python file in the appropriate subdirectory of functions/
2. Define a cog class with your commands
3. Implement a setup function
4. Test locally with the guild sync command
5. When ready, sync globally

Best Practices

When extending Ui-Py, follow these guidelines:

1. Keep commands organized by purpose and category
2. Use type hints for better code quality
3. Follow Discord rate limits for API calls
4. Handle errors gracefully and provide user feedback
5. Document your commands with clear descriptions
6. Use async/await correctly to avoid blocking the bot
7. Leverage Discord's features like embeds and buttons for rich interactions