A powerful community management bot designed specifically for the PESU Discord Server. This bot provides essential moderation tools, anonymous messaging capabilities, user linking systems, and various utility commands to enhance the Discord experience for PESU students.

The bot is built with security and privacy in mind, ensuring safe and effective community management while maintaining user confidentiality.

The bot is currently deployed and active in the PESU Discord Server. Use slash commands to interact with the bot:

• Type / in any channel to see available commands
• Use /help for detailed command documentation
• Contact moderators for support with bot-related issues

1. Check our project board for current work
2. Read the contribution guidelines
3. Set up your development environment
4. Create a branch: (discord-username)/feature-description
5. Submit a PR to the dev branch

For detailed development setup and contribution instructions, see our Contributing Guide.

├── pyproject.toml              # Project metadata and dependencies
├── uv.lock                     # uv lockfile
├── Dockerfile                  # Container image definition
├── LICENSE                     # Project license
├── README.md                   # This file
├── scripts/                    # Operational scripts
│   └── sync_guild_commands.py  # Deploy-time guild command sync
└── src/                        # Discord bot package (run via `python -m src`)
    ├── __init__.py             # Package bootstrap: env loading, logging, version
    ├── __main__.py             # Entry point for `python -m src`
    ├── bot.py                  # DiscordBot subclass (setup_hook, cog loading, events)
    ├── .env.example            # Example environment variables
    ├── data/                   # Static data files
    │   └── faq.json            # FAQ responses data
    ├── cogs/                   # Bot functionality modules (Discord.py cogs)
    │   ├── events.py           # Event handling (member joins, ghost pings, etc.)
    │   ├── anon.py             # Anonymous messaging system
    │   ├── help.py             # Help and command documentation
    │   ├── link.py             # User linking and verification
    │   ├── mod.py              # Moderation commands
    │   └── utils.py            # Utility commands (ping, uptime, etc.)
    └── utils/                  # Shared utilities and configuration helpers
        ├── config.py           # Environment, guild/role/channel IDs and access helpers
        └── general.py          # General helper functions

The bot uses Discord.py's cogs system to organize functionality into modular components:

• Events Cogs: Handle Discord events such as member joins, message events, and server updates
• Slash Command Cogs: Implement modern Discord slash commands for user interactions
• Utility Functions: Shared helper functions used across different cogs

The bot maintains several MongoDB collections:

• link: Stores Discord-PESU account links
• student: Student linking data
• anonban: Anonymous messaging ban records
• mute: Server mute records

The bot's behavior is controlled primarily through environment variables and code-based configuration:

Refer to our Contributing Guide for environment setup and the list of variables: .github/CONTRIBUTING.md. An example file is provided at src/.env.example.

Holds guild-specific role and channel ID mappings and exposes helpers like get_role/get_channel.

Stores frequently asked questions and their responses for quick access.

Made with ❤️ by

Powered by contrib.rocks

We welcome contributions from the PESU community! Whether you're fixing bugs, adding new features, or improving documentation, your help is appreciated.

👉 Read our detailed Contributing Guide for complete setup instructions and development workflow.

The project uses an immutable-image promotion flow designed for free-tier hosting:

• PR to dev: lint + source checks + Docker image build validation (no push)
• Merge to dev: checks run again, image is pushed to GHCR as <commit_sha>, then deployed to dev
• Post-dev health success: deployed SHA is retagged as dev
• Manual prod promotion: dev -> main fast-forward, deploy the same immutable SHA, and retag as prod only on success
• Prod failure path: automatic rollback deploy to the previous prod tag

Key deployment files:

• .github/workflows/dev_deploy.yml
• .github/workflows/prod_deploy.yml
• .github/workflows/build_and_push_image.yml
• .github/workflows/ghcr_cleanup.yml
• ops/deploy/README.md

• No Credential Storage: The bot does not store Discord or PESU passwords
• Secure Database: All data is stored securely in MongoDB with proper access controls
• Role-based Access: Commands are restricted based on user permissions and server roles

• Active Development: The bot is actively maintained and updated
• Community Driven: Features are developed based on community needs
• Production Ready: Currently deployed and serving the PESU Discord community

This project is licensed under the MIT License - see the LICENSE file for details.

For questions, support, or feature requests, please visit our project board or join the discussion on the PESU Discord server.