[FEATURE] Discord - Tournaments

[Flegma]

Add the ability to create Tournament voice rooms and move players for each match, etc.

[Flegma]

Detailed Implementation Plan: Tournament Discord Voice Channels

Overview

Extend the Discord bot to automatically manage voice channels for tournament matches. This includes:

• A muted "Ready Room" voice channel (named after the tournament) where players wait between matches — nobody can speak except Discord admins
• Per-match team voice channels with descriptive names (e.g., "Fnatic - Grand Finals", "Navi - Grand Finals") created under a tournament category
• Automatic player movement: players are moved from the ready room to their match voice channels when the match enters WaitingForCheckIn, and moved back when the match ends
• Cleanup: match voice channels are deleted after the match finishes; ready room + category are deleted when the tournament ends
• Warning messages posted in the match Discord thread for players who haven't linked their Discord account

Feature Toggle

This is opt-in per tournament via two new tournament settings:

• discord_guild_id (text) — which Discord server to create channels in
• discord_voice_enabled (boolean, default false) — enables/disables the feature

These appear alongside the existing tournament Discord webhook/notification settings in the web UI.

---

Implementation Steps

1. Database Migration

Add columns to tournaments table:

ALTER TABLE tournaments ADD COLUMN IF NOT EXISTS discord_guild_id text;
ALTER TABLE tournaments ADD COLUMN IF NOT EXISTS discord_voice_enabled boolean NOT NULL DEFAULT false;

Update Hasura metadata (public_tournaments.yaml) to include these columns in all role permissions (insert, update, select).

2. Hasura Event Trigger on Tournaments

Currently, tournaments have SQL-level triggers but no Hasura event trigger to notify the NestJS API of status changes. Add a tournament_events event trigger that fires on status column updates — this enables the API to react when a tournament goes Live, gets Cancelled, or Finishes.

event_triggers:
  - name: tournament_events
    definition:
      enable_manual: true
      update:
        columns:
          - status
    retry_conf:
      interval_sec: 10
      num_retries: 3
      timeout_sec: 60
    webhook: '{{HASURA_GRAPHQL_EVENT_HOOK}}'

3. Round Label Utility (Backend)

Port the frontend round label logic (web/utilities/tournamentRoundLabels.ts) to the API side. This converts bracket data (round number, path, stage type, team count) into human-readable labels like "Grand Finals", "Semi-Finals", "WB Round 1", "LB Final", etc.

Uses hardcoded English strings since Discord channel names don't support i18n.

4. New Service: DiscordTournamentVoiceService

Core service with these methods:

createTournamentReadyRoom(tournamentId)

• Query tournament for guild_id, name, discord_voice_enabled
• Create a Discord category channel named after the tournament
• Create a voice channel "Ready Room" under it with permissions: @everyone can connect but cannot speak, bot has full perms
• Cache: tournament:{id}:voice → { guildId, categoryId, readyRoomId }

createMatchVoiceChannels(matchId)

• Query tournament_brackets to find the tournament for this match
• Check if discord_voice_enabled is true
• Get team names via match lineup name computed field
• Compute round label from bracket data
• Create 2 voice channels under tournament category using the existing DiscordBotVoiceChannelsService.createMatchVoiceChannel() — with originalChannelId set to the ready room (so cleanup moves players back there)
• Channel names: "{Team Name} - {Round Label}" (e.g., "Fnatic - Grand Finals")

movePlayersToMatchChannels(matchId)

• Query lineup players and resolve their discord_id from the players table
• Move each linked player to their team's voice channel using existing moveMemberToTeamChannel()
• Post a warning in the match Discord thread listing any players without Discord linked

removeTournamentVoice(tournamentId)

• Delete ready room + category channel
• Clear cache

5. Modify Existing Voice Channel Service

Add an optional channelName parameter to createMatchVoiceChannel():

name: channelName || `${lineupId} [${matchId}]`

Existing callers (ScheduleMatch.ts) are unchanged. Tournament voice passes the descriptive name.

6. Tournament Lifecycle Hooks

In tournaments.controller.ts, add a @HasuraEvent() handler for tournament_events:

• Status → Live: Call createTournamentReadyRoom()
• Status → Finished/Cancelled/CancelledMinTeams: Call removeTournamentVoice()
• Paused → Live (resume): Recreate ready room if not cached

7. Match Lifecycle Hooks

In matches.controller.ts match_events():

• When match status changes to WaitingForCheckIn: call createMatchVoiceChannels() + movePlayersToMatchChannels()
• No changes needed for cleanup — the existing removeDiscordIntegration() already calls removeTeamChannels() on terminal match status, which:
  1. Moves players back to originalChannelId (= ready room)
  2. Deletes the match voice channels

8. Module Wiring

New NestJS module DiscordTournamentVoiceModule importing:

• DiscordBotModule, DiscordBotMessagingModule, DiscordBotVoiceChannelsModule
• HasuraModule, CacheModule

Import into TournamentsModule and MatchesModule.

9. Web UI Updates

Add discord_guild_id and discord_voice_enabled fields to the tournament Discord settings form (alongside existing webhook/notification settings).

---

Architecture Summary

Tournament → Live
  └── Create category channel + muted Ready Room

Bracket gets two teams → SQL trigger creates match → WaitingForCheckIn
  ├── Create "Team A - Round Label" voice channel
  ├── Create "Team B - Round Label" voice channel  
  ├── Move players from Ready Room → team channels
  └── Post warning for unlinked Discord players

Match → Terminal (Finished/Canceled/Forfeit/etc.)
  ├── Move players back to Ready Room (existing logic)
  └── Delete match voice channels (existing logic)

Tournament → Finished/Cancelled
  └── Delete Ready Room + category

Key Design Decisions

• Reuses existing infrastructure: The existing DiscordBotVoiceChannelsService handles channel creation, player movement, and cleanup. Only needs a channelName param added.
• Original channel = ready room: By setting originalChannelId to the ready room when creating match voice channels, the existing removeTeamChannels() cleanup automatically moves players back to the right place.
• Database-driven match creation: Tournament matches are created by SQL triggers, so voice channel creation hooks into the match_events Hasura event (not a direct API call).
• Opt-in per tournament: The feature only activates when both discord_guild_id is set and discord_voice_enabled is true.

[lukepolo]

we already have some of this in the discord bot already, i would instead of a tournament ddiscor channel sevice, just leveage the bot services, as it already does alot of clean up etc already.

[Flegma]

I dont think that we need more Discord commands - the Discord bot client (discord.js) is already initialized in DiscordBotService with the GuildVoiceStates intent. The new DiscordTournamentVoiceService just uses that same client (via DiscordBotService) to create channels and move players, same as the existing DiscordBotVoiceChannelsService already does for non-tournament matches created via /competitive, /wingman, /duel commands.

So it's all server-side, automatic - no slash commands, no user interaction required. The tournament organizer just enables discord_voice_enabled and sets the discord_guild_id in the web UI settings, and everything happens automatically as the tournament progresses.

[lukepolo]

It’s not about slash commands : we have services that deal with discord channels etc

[Flegma]

Reused from DiscordBotVoiceChannelsService:

• createMatchVoiceChannel() — creates voice channels per team (only change: add optional channelName param so we can pass "Fnatic - Grand Final" instead of "lineupId [matchId]")
• moveMemberToTeamChannel() — moves a player to their team's channel (used as-is)
• removeTeamChannels() — moves players back to originalChannelId and deletes channels (used as-is — the trick is we set originalChannelId = ready room when creating tournament match channels, so cleanup automatically returns players to the ready room)
• setVoiceCache() / getVoiceCache() — same cache pattern (used internally by the above)

Reused from DiscordBotMessagingService:

• getCategory() — get-or-create a Discord category channel (used for the tournament category)
• sendToMatchThread() — post the "unlinked Discord players" warning message

New in DiscordTournamentVoiceService:

Only the orchestration logic that's specific to tournaments:

1. createTournamentReadyRoom() — creates the muted ready room (new concept, no existing code for this)
2. createMatchVoiceChannels() — queries bracket data, computes round label, then calls the existing createMatchVoiceChannel() with tournament-specific params
3. movePlayersToMatchChannels() — queries lineup players for discord_ids, then calls the existing moveMemberToTeamChannel() per player
4. removeTournamentVoice() — deletes ready room + category on tournament end

So this new service is essentially a thin orchestrator on top of the existing infrastructure. The only code-level change to existing services is adding channelName?: string to createMatchVoiceChannel().

[Flegma]

5stackgg/web#258
5stackgg/api#127