FightRise Codebase Reference

A comprehensive reference guide for understanding and working with the FightRise codebase.

Table of Contents

1. Project Overview
2. Architecture
3. Database Models
4. Services
5. Commands & Handlers
6. Code Patterns
7. Key Files
8. Testing

Project Overview

FightRise is a Discord bot and web portal for running Start.gg fighting game tournaments entirely within Discord.

Tech Stack

Data Flow

1. Start.gg Polling: BullMQ jobs poll Start.gg GraphQL API (no webhooks)
2. Match Ready: Bot creates Discord thread, pings players
3. Check-in: Players use Discord buttons to check in
4. Score Reporting: Players report scores via buttons; loser confirmation auto-submits to Start.gg
5. Sync Back: Results reported to Start.gg via GraphQL mutation

Architecture

Directory Structure

fightrise-bot/
├── apps/
│   ├── bot/                    # Discord bot application
│   │   └── src/
│   │       ├── commands/        # Slash commands (9)
│   │       ├── events/          # Discord event handlers
│   │       ├── handlers/        # Button/modal interactions
│   │       ├── services/        # Business logic (6)
│   │       ├── workers/         # BullMQ workers
│   │       ├── index.ts         # Bot entry point
│   │       └── __tests__/       # Tests & harness
│   │
│   └── web/                    # Next.js web portal
│       └── app/
│           ├── (auth)/          # Auth pages
│           ├── api/             # API routes
│           ├── dashboard/       # User dashboard
│           ├── tournaments/     # Tournament pages
│           └── account/         # Account settings
│
├── packages/
│   ├── database/               # Prisma schema & client
│   ├── startgg-client/         # GraphQL API wrapper
│   ├── shared/                 # Types & utilities
│   └── ui/                     # React components
│
└── docker/                     # Docker configurations

Implementation Status

Database Models

All 11 Prisma Models

Enums

// Tournament state
enum TournamentState {
  CREATED, REGISTRATION_OPEN, REGISTRATION_CLOSED,
  IN_PROGRESS, COMPLETED, CANCELLED
}

// Match state
enum MatchState {
  NOT_STARTED, CALLED, CHECKED_IN, IN_PROGRESS,
  PENDING_CONFIRMATION, COMPLETED, DISPUTED, DQ
}

// Registration
enum RegistrationSource { STARTGG, DISCORD, MANUAL }
enum RegistrationStatus { PENDING, CONFIRMED, CANCELLED, DQ }
enum AdminRole { OWNER, ADMIN, MODERATOR }

Services

Bot Services (`apps/bot/src/services/`)

Polling Intervals

const POLL_INTERVALS = {
  ACTIVE: 15 * 1000,        // 15s during matches
  REGISTRATION: 60 * 1000,   // 1min during registration
  INACTIVE: 300 * 1000,      // 5min when inactive
};

Commands & Handlers

Slash Commands (`apps/bot/src/commands/`)

Button Handlers (`apps/bot/src/handlers/`)

Code Patterns

Discord Command Pattern

// apps/bot/src/commands/example.ts
import { SlashCommandBuilder } from 'discord.js';

export const exampleCommand = {
  data: new SlashCommandBuilder()
    .setName('example')
    .setDescription('Example command')
    .addStringOption(option =>
      option.setName('input').setDescription('Input').setRequired(true)
    ),

  async autocomplete(interaction: AutocompleteInteraction) {
    // Handle autocomplete
  },

  async execute(interaction: ChatInputCommandInteraction) {
    await interaction.deferReply({ ephemeral: true });
    // Command logic
  },
};

Button Handler Pattern

// apps/bot/src/handlers/buttonHandlers.ts
export interface ButtonHandler {
  prefix: string;
  execute(interaction: ButtonInteraction, parts: string[]): Promise<void>;
}

export const buttonHandlers: Record<string, ButtonHandler> = {
  [INTERACTION_PREFIX.CHECKIN]: checkinHandler,
  [INTERACTION_PREFIX.REPORT]: scoreHandler,
};

Idempotent Database Operations

// Use updateMany with conditions for idempotency
const result = await prisma.match.updateMany({
  where: { id: matchId, state: MatchState.NOT_STARTED },
  data: { discordThreadId: thread.id, state: MatchState.CALLED },
});

if (result.count === 0) {
  // Already processed - skip
  return;
}

Database Transactions

// Atomic operations
await prisma.$transaction(async (tx) => {
  await tx.match.update({ where: { id }, data: { state: 'IN_PROGRESS' } });
  await tx.matchPlayer.updateMany({ where: { matchId: id }, data: { isCheckedIn: true } });
});

Key Files

Bot

Database

Start.gg Client

Web

Testing

Test Infrastructure

Test Commands

# Start infrastructure
npm run docker:infra

# Push schema
npm run docker:db:push

# Run tests
npm run docker:test           # Unit tests
npm run docker:test:integration  # Integration tests
npm run docker:test:e2e       # E2E tests
npm run docker:lint           # Linting

# Smoke tests (requires .env)
npm run docker:test:smoke

Test Harnesses

• Discord: apps/bot/src/__tests__/harness/ - Mock client, interactions, channels
• Start.gg: packages/startgg-client/src/__mocks__/ - MSW handlers
• Database: packages/database/src/__tests__/ - Testcontainers setup

Environment Variables

# Database
DATABASE_URL="postgresql://fightrise:fightrise@localhost:5432/fightrise"

# Redis
REDIS_URL="redis://localhost:6379"

# Discord
DISCORD_TOKEN="bot-token"
DISCORD_CLIENT_ID="client-id"
DISCORD_CLIENT_SECRET="client-secret"

# Start.gg
STARTGG_API_KEY="api-key"

# NextAuth
NEXTAUTH_SECRET="secret"
NEXTAUTH_URL="http://localhost:3000"

Quick Reference

# Development
npm run docker:dev           # Full stack
npm run dev -- --filter=@fightrise/bot  # Bot only
npm run dev -- --filter=@fightrise/web   # Web only

# Database
npm run docker:db:generate   # Generate client
npm run docker:db:push      # Push schema

# Commands
npm run docker:deploy        # Deploy Discord commands

# Testing
npm run docker:test && npm run docker:test:integration