Documentation Index
Fetch the complete documentation index at: https://mintlify.com/VasquezRivero92/Discord_Faceit/llms.txt
Use this file to discover all available pages before exploring further.
The bot uses Google Cloud Firestore (via the Firebase Admin SDK) as its persistence layer. Data is organized across several top-level collections. All collection names are defined as constants in database.js and are reproduced here for reference. Document IDs are noted for each collection — most are either the Discord user ID or a Faceit match ID.
Several hot-path reads are served from in-memory caches to reduce Firestore read quotas. Settings (global and per-guild) are cached for 30 seconds. Ready players are cached for 30 seconds. Active matches are cached for 10 seconds. User profiles (by Discord ID, Faceit ID, and Faceit nickname) are cached for 5 minutes. The cache is invalidated on any write that touches the corresponding document.
faceit_users
Stores every verified Discord ↔ Faceit account link. This is the largest and most frequently read collection.
Document ID: Discord user ID, or {guildId}_{discordId} for multi-guild installs.
| Field | Type | Description |
|---|
discordId | string | The Discord user ID (snowflake). Redundantly stored inside the document for queries that scan the collection. |
guild_id | string | null | Discord guild ID this link belongs to. |
faceit_player_id | string | Faceit UUID of the linked player. |
faceit_nickname | string | Faceit username at the time of linking. |
faceit_nickname_lower | string | Lowercase version of faceit_nickname for case-insensitive queries. |
faceit_level | number | Faceit skill level (1–10). Updated on role sync. |
faceit_elo | number | Faceit ELO rating. Updated on role sync. |
linkedAt | Timestamp | Server timestamp set when the account is first linked. |
updatedAt | Timestamp | Server timestamp set on every update. |
rol | string | Web panel role: "usuario", "admin", or "global_admin". |
servidor | string | null | Guild ID the admin role is scoped to. |
discord_username | string | Cached Discord username (updated lazily). |
discord_displayName | string | Cached Discord display name. |
discord_avatar | string | Cached Discord avatar URL. |
mixton_ready | boolean | true when the player has run /mixton_listo and is in the draft queue. |
mixton_ready_at | number | Unix timestamp (ms) when the player joined the queue. |
mixton_guild_id | string | Guild ID of the Mixton lobby the player queued for. |
mixton_tier_override | string | null | Admin-assigned ELO tier override: "S", "A", "B", "C", or null. |
faceit_pending_verifications
Temporary documents created when a user starts the /verificar_fc flow but has not yet confirmed their code. Documents are automatically expired after 15 minutes and deleted when verification completes.
Document ID: Discord user ID.
| Field | Type | Description |
|---|
faceitNickname | string | The Faceit username the user is attempting to link. |
code | string | The verification code sent to the user. |
expiresAt | number | Unix timestamp (ms) after which the pending verification is invalid. |
faceit_active_matches
One document per in-progress Faceit match (or manually created match). Documents are removed when the match finishes, is cancelled, or is force-cleaned via the admin panel.
Document ID: Faceit match ID, or manual_{timestamp}_{random} for web-created matches.
| Field | Type | Description |
|---|
id | string | The match ID (mirrors the document ID). |
entity_custom_name | string | Hub or custom name for the match (e.g. "Club"). |
game | string | Game identifier (e.g. "cs2"). |
map | string | Map name or "Votando..." if voting is pending. |
location | string | Server location or "Votando..." if voting is pending. |
faction1_name | string | Display name for Team 1 (e.g. "Equipo A"). |
faction2_name | string | Display name for Team 2 (e.g. "Equipo B"). |
faction1_roster | array | Array of { id, nickname, discord_id } for Team 1 players. |
faction2_roster | array | Array of { id, nickname, discord_id } for Team 2 players. |
faction1_vc_id | string | null | Discord voice channel ID created for Team 1. |
faction2_vc_id | string | null | Discord voice channel ID created for Team 2. |
message_id | string | null | Discord message ID of the match announcement embed. |
original_voice_states | object | Map of { discordId: voiceChannelId } recording where each player was before being moved. Used to restore positions on cleanup. |
creator_id | string | null | Discord user ID of the admin who launched a manual match. null for Faceit webhook matches. |
guild_id | string | Discord guild ID this match belongs to. |
startedAt | number | Unix timestamp (ms) when the match document was created. Used for timeout calculations. |
createdAt | Timestamp | Server timestamp. |
faceit_matches_history
Completed matches archived for the history view. Documents are written by the webhook handler when a match finishes.
Document ID: Faceit match ID.
| Field | Type | Description |
|---|
id | string | Match ID. |
entity_custom_name | string | Hub or custom name. |
game | string | Game identifier. |
map | string | Final map played. |
location | string | Server location. |
faction1_name | string | Team 1 display name. |
faction2_name | string | Team 2 display name. |
faction1_score | number | Team 1 final score. |
faction2_score | number | Team 2 final score. |
winner | string | "faction1" or "faction2". |
faction1_roster | array | Array of { id, nickname, discord_id }. |
faction2_roster | array | Array of { id, nickname, discord_id }. |
guild_id | string | Discord guild ID. |
createdAt | Timestamp | Server timestamp when the match result was recorded. |
faceit_config
A multipurpose configuration collection. Each document serves a distinct role, identified by its document ID.
settings
Global bot settings and feature flags. Cached for 30 seconds. These values are merged with .env at runtime — Firestore values take precedence.
| Field | Type | Default | Description |
|---|
discordGuildId | string | env | Primary guild ID. |
discordLinkChannelId | string | env | Channel for /verificar_fc. |
discordMatchesChannelId | string | env | Match announcements channel. |
discordRolesChannelId | string | env | Role change notifications channel. |
discordStatusChannelId | string | env | Server status channel. |
discordWaitingRoomChannelId | string | env | Waiting room voice channel. |
discordAdminAlertsChannelId | string | env | Staff alerts channel. |
discordSupportChannelId | string | env | Support panel channel. |
faceitHubId | string | env | Faceit Hub UUID. |
faceitLeaderboardId | string | env | Faceit Leaderboard UUID. |
adminRoleName | string | "ADMIN" | Discord role granting admin access. |
matchTimeoutMinutes | number | 120 | Auto-expiry timeout for active matches. |
autoWelcomeDm | boolean | true | Send welcome DM to new server members. |
autoRoleSync | boolean | true | Automatically sync Faceit level roles. |
autoVoiceChannels | boolean | true | Create voice channels when a match starts. |
autoMovePlayers | boolean | true | Auto-move players to match voice channels. |
matchAnnouncements | boolean | true | Post match started/finished embeds. |
serverStatusAnnouncements | boolean | true | Keep the server status embed updated. |
liveMatchPanel | boolean | true | Maintain the live match panel embed. |
webhookValidation | boolean | false | Validate X-Signature on Faceit webhooks. |
adminCallNotifications | boolean | true | Send staff alerts for support calls. |
updatedAt | Timestamp | — | Last update timestamp. |
guild_settings
Per-guild settings overrides stored in a separate top-level collection (not inside faceit_config). Document ID is the guild ID. Fields mirror the settings document in faceit_config — only fields present in this document override the corresponding global default at runtime.
Used by getEffectiveConfigForGuild(guildId) in config/index.js to merge guild-specific values on top of the global configuration.
panel (inside faceit_config)
Persists the Discord message ID and channel ID of the live match panel embed so it can be updated in-place across restarts.
| Field | Type | Description |
|---|
messageId | string | Discord message ID of the live panel. |
channelId | string | Discord channel ID where the panel lives. |
updatedAt | Timestamp | Last update timestamp. |
status_panel (inside faceit_config)
Same shape as panel but for the server status embed.
| Field | Type | Description |
|---|
messageId | string | Discord message ID of the status embed. |
channelId | string | Discord channel ID where the status embed lives. |
updatedAt | Timestamp | Last update timestamp. |
messages (inside faceit_config)
Customizable message templates for the welcome DM and support panel embed.
| Field | Type | Description |
|---|
welcomeTitle | string | Title for the welcome DM embed. |
welcomeDescription | string | Body text — supports {username}, {clubUrl}, {linkChannelMention} placeholders. |
welcomeColor | string | Hex color for the welcome embed (e.g. "#FF5500"). |
supportTitle | string | Title for the support panel embed. |
supportDescription | string | Body text for the support panel. |
supportColor | string | Hex color for the support embed. |
updatedAt | Timestamp | Last update timestamp. |
mixton_lobby_{guildId} (inside faceit_config)
Persistent state for the Mixton Arena lobby. One document per guild, keyed as mixton_lobby_{guildId}. A default document (key mixton_lobby) is used for single-guild deployments.
| Field | Type | Description |
|---|
teams | array | Array of team objects: { id, name, captain, players[] }. Captain and each player are full player profile objects including discordId, faceit_nickname, faceit_level, faceit_elo, and discordUser. |
pickOrder | array | Ordered array of team IDs defining the draft pick sequence. |
currentPickIndex | number | Index into pickOrder pointing to the team whose captain is currently picking. |
draftStarted | boolean | true after POST /mixton-start is called. |
draftFinished | boolean | true after the match is created via POST /mixton-create-match. |
updatedAt | number | Unix timestamp (ms) of the last state write. |
faceit_support_calls
Support call records created when a player presses the “Call Admin” button in the support panel channel.
Document ID: Auto-generated support call ID.
| Field | Type | Description |
|---|
id | string | Support call ID. |
match_id | string | Active Faceit match ID at the time of the call. |
match_url | string | Direct URL to the Faceit match room. |
faceit_player_id | string | Faceit UUID of the requesting player. |
faceit_nickname | string | Faceit username. |
discord_id | string | Discord user ID of the requesting player. |
description | string | User-provided issue description. |
status | string | "pendiente" (open) or "atendida" (resolved). |
claimedBy | string | null | Discord tag or "WebAdmin (username)" of the admin who resolved it. |
claimedAt | number | null | Unix timestamp (ms) when the call was resolved. |
guild_id | string | Discord guild ID. |
createdAt | Timestamp | Server timestamp. |
faceit_bot_logs
Bot activity log entries. Only error, warn, and system-sourced entries are written to keep Firestore write usage low. Entries older than 7 days are pruned automatically by db.pruneOldLogs().
Document ID: Auto-generated by Firestore.
| Field | Type | Description |
|---|
level | string | Log level: "error", "warn", "info", or "success". |
message | string | Human-readable log message. |
source | string | Origin of the log: "bot", "system", or a command/event name. |
guild_id | string | null | Guild ID if the event is guild-specific. |
createdAt | Timestamp | Server timestamp. |