SquadMakerBot

Build balanced teams for ANY sport or activity!

SquadMaker is a universal, configuration-driven Telegram bot that helps you organize events and form balanced teams. Whether it's volleyball, football, basketball, work projects, or any other team-based activity, SquadMaker has you covered.

Key Features

• Universal Design: Works for ANY team-based activity
• Configuration-Driven: Add new sports/activities via JSON, no code changes needed
• Seamless UX: One-click join in group chats, private position selection
• Balanced Teams: Smart algorithm distributes participants fairly
• Inline Mode: Easily share events in group chats

🚀 Quick Start

Prerequisites

• Go 1.21+ (for building from source)
• Docker & Docker Compose (for containerized deployment)
• Telegram Bot Token from @BotFather

Option 1: Docker (Recommended)

1. Clone the repository

   git clone https://github.com/avpv/squad-maker-bot.git
   cd squad-maker-bot

2. Configure environment

   cp .env.example .env
   # Edit .env and set your TELEGRAM_BOT_TOKEN

3. Start the bot

   docker-compose up -d

4. Check logs

   docker-compose logs -f

Option 2: Build from Source

1. Clone and install dependencies

   git clone https://github.com/avpv/squad-maker-bot.git
   cd squad-maker-bot
   make deps

2. Set environment variables

   export TELEGRAM_BOT_TOKEN="your_token_here"
   export SPORT_TYPE="volleyball"  # or football, basketball, work

3. Build and run

   make build
   make run

📱 How to Use

For Event Organizers

1. Create an Event

   • Send /create to the bot in a private chat
   • Follow the prompts to set name, description, and date/time

2. Publish to Group

   • Go to your group chat
   • Type @YourBotName (inline mode)
   • Select your event from the list
   • Send it to the group

3. Form Teams

   • When ready, use /formteams
   • Select the event
   • The bot generates balanced teams!

For Participants

1. Join an Event

   • Click ✅ Join on the event message in your group chat
   • The bot will send you a private message

2. Select Positions

   • Choose your positions from the private message
   • Click ✅ Done when finished

3. Leave if Needed

   • Click ❌ Leave on the event message to cancel

⚙️ Configuration

SquadMaker supports two configuration modes:

Built-in Sports

Set the SPORT_TYPE environment variable:

# Available options
SPORT_TYPE=volleyball   # Default
SPORT_TYPE=football
SPORT_TYPE=basketball
SPORT_TYPE=work        # Work/project teams

Custom Configuration

Create a JSON file and set SPORT_CONFIG_PATH:

SPORT_CONFIG_PATH=./configs/examples/ultimate-frisbee.json

Example configuration:

{
  "name": "Ultimate Frisbee",
  "emoji": "🥏",
  "positions": [
    {"id": "HANDLER", "name": "Handler", "emoji": "🎯"},
    {"id": "CUTTER", "name": "Cutter", "emoji": "⚡"}
  ],
  "min_players": 4,
  "max_players": 7,
  "default_teams": 2,
  "allow_multi_pos": true,
  "bot_username": "squadmakerbot",
  "welcome_message": "Welcome to SquadMaker! Build balanced teams."
}

See configs/examples/ for more examples.

📚 Documentation

• EXTENDING.md - How to create custom sport configurations
• ARCHITECTURE.md - System design and architecture
• BOTFATHER_SETUP.md - Complete BotFather configuration guide

🛠️ Commands

Command	Description
/start	Welcome message and quick start guide
/help	Detailed help information
/create	Create a new event (private chat only)
/myevents	List your active events
/formteams	Generate balanced teams for an event
/cancel	Cancel current operation

🏗️ Project Structure

squad-maker-bot/
├── cmd/bot/              # Application entry point
├── internal/
│   ├── bot/             # Bot logic and handlers
│   ├── database/        # SQLite database layer
│   └── models/          # Data structures
├── config/              # Configuration loading
├── configs/examples/    # Example sport configs
├── migrations/          # Database migrations
├── Dockerfile           # Docker configuration
├── docker-compose.yml   # Docker Compose setup
└── Makefile            # Build automation

🐳 Docker Deployment

The bot includes complete Docker support:

# docker-compose.yml
services:
  bot:
    build: .
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - SPORT_TYPE=volleyball
    volumes:
      - ./data:/data  # Persist database

Useful commands:

make docker-build    # Build Docker image
make docker-run      # Start bot
make docker-stop     # Stop bot
make docker-logs     # View logs

🎯 Built-in Sport Configurations

SquadMaker comes with 4 pre-configured sports:

🏐 Volleyball

• Positions: Setter, Opposite, Outside Hitter, Middle Blocker, Libero
• Team size: 2-6 players

⚽ Football

• Positions: Goalkeeper, Defender, Midfielder, Forward
• Team size: 5-11 players

🏀 Basketball

• Positions: Point Guard, Shooting Guard, Small Forward, Power Forward, Center
• Team size: 3-5 players

💼 Work Teams

• Positions: Developer, Designer, PM, QA, DevOps, Marketing
• Team size: 2+ players (unlimited)

🔧 Environment Variables

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	✅ Yes	-	Bot token from @BotFather
DATABASE_PATH	No	teambot.db	SQLite database path
SPORT_TYPE	No	volleyball	Built-in sport type
SPORT_CONFIG_PATH	No	-	Custom config file path

🧪 Development

# Install dependencies
make deps

# Build the bot
make build

# Run locally
make run

# Run tests
make test

# Format code
make fmt

# Clean build artifacts
make clean

📋 Requirements

• Go: 1.21 or higher
• SQLite: 3.x (automatically included)
• Docker: 20.10+ (optional, for containerized deployment)

🤝 Contributing

Contributions are welcome! Here are some ways you can help:

• 🐛 Report bugs
• 💡 Suggest new features or sport configurations
• 📝 Improve documentation
• 🔧 Submit pull requests

📄 License

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

🙏 Acknowledgments

Built with:

• go-telegram-bot-api - Telegram Bot API wrapper
• SQLite - Database
• Go - Programming language

📞 Support

• 🐛 Report Issues
• 📖 Documentation
• 💬 Telegram: @SquadMakerBot

---

Made with ❤️ for team sports and collaborative activities