Buckshot Tournament

A Next.js tournament management application for the Buckshot Roulette game, featuring real-time match tracking, leaderboards, and tournament management.

Features

• Match Management: Create and manage matches with up to 4 players
• Real-time Scoring: Track items used and actions performed during matches
• Leaderboard System: Automatic leaderboard updates with player rankings
• Tournament System: Create and manage tournaments with custom scoring rules
• Live Match Tracking: Turn-based gameplay with visual indicators
• Action History: Undo functionality for correcting mistakes

Technology Stack

• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS
• Backend: Next.js API Routes
• Database: PostgreSQL with Prisma ORM
• Deployment: Docker & Docker Compose

Prerequisites

• Docker and Docker Compose

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd buckshot-tournament
   

2. Create environment file

   cp .env.example .env
   

   Then edit the .env file with your preferred database credentials:

   POSTGRES_USER=tournament_user
   POSTGRES_PASSWORD=tournament_pass
   POSTGRES_DB=tournament_db
   DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}?schema=public
   

3. Start the application

   docker-compose up -d
   

   Note: The app service will wait for the database to be healthy before starting.

4. Access the application

   • Open your browser and navigate to http://localhost:3000
   • The database will be automatically set up with migrations

That's it! Docker handles everything including:

• PostgreSQL database setup with health checks
• Node.js application environment
• Database migrations (runs automatically on startup)
• Package installation
• Production build and server startup

The app runs as a production build inside the container. After changing code, rebuild with docker-compose up -d --build. For live-reload development, run the app locally instead (see below).

Local Development (Alternative)

If you prefer to run without Docker, you'll need:

• Node.js 24 or higher
• PostgreSQL installed locally

# Install dependencies
npm install

# Set up local database URL in .env
DATABASE_URL="postgresql://username:password@localhost:5432/buckshot_tournament"

# Run migrations and start
npx prisma migrate dev
npm run dev

Docker Commands

# Start the application (database will be ready before app starts)
docker-compose up -d

# View logs
docker-compose logs -f app

# View database logs
docker-compose logs -f db

# Stop the application
docker-compose down

# Stop and remove volumes (complete cleanup)
docker-compose down -v

# Rebuild and restart
docker-compose up -d --build

# Access the app container shell
docker-compose exec app sh

Available Scripts (when running locally)

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint

Database Management

All database operations are handled automatically by Docker. However, if you need to run Prisma commands:

Using Docker

# Open Prisma Studio
docker-compose exec app npx prisma studio

# Reset database
docker-compose exec app npx prisma migrate reset

# Generate client
docker-compose exec app npx prisma generate

Local Development Only

• npx prisma studio - Open Prisma Studio (database GUI)
• npx prisma migrate dev - Run migrations in development
• npx prisma migrate reset - Reset database

Application Structure

src/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   │   ├── leaderboard/   # Leaderboard endpoints
│   │   ├── matchmaker/    # Match management endpoints
│   │   ├── players/       # Player management
│   │   └── tournament/    # Tournament management
│   ├── leaderboard/       # Leaderboard page
│   ├── login/            # Login page (stub)
│   ├── matchmaker/       # Match tracking interface
│   └── tournament/       # Tournament configuration
├── components/           # Reusable UI components
├── lib/                 # Utility libraries
├── types/               # TypeScript type definitions
└── generated/           # Generated Prisma client

How to Use

1. Tournament Setup

• Navigate to /tournament to create a new tournament
• Configure scoring rules for items and actions
• Set tournament parameters (rounds, lives, etc.)

2. Match Management

• Go to /matchmaker to start a new match
• Add up to 4 players
• Start the match to begin tracking

3. During a Match

• Select the current player
• Click items/actions as they're used during gameplay
• Use next/previous buttons to change turns
• The system automatically calculates scores based on tournament rules

4. After a Match

• End the match to finalize scores
• Leaderboard is automatically updated
• View results in /leaderboard

API Endpoints

Match Management

• GET /api/matchmaker - Get current match session
• POST /api/matchmaker - Create new match session
• POST /api/matchmaker/status - Start/end match
• POST /api/matchmaker/actions - Add item/action to match
• POST /api/matchmaker/turn - Change current turn
• POST /api/matchmaker/players - Add/remove players
• POST /api/matchmaker/reset - Reset match
• POST /api/matchmaker/undo - Undo last action

Leaderboard

• GET /api/leaderboard - Get leaderboard data
• POST /api/leaderboard/update-match - Update leaderboard from match

Tournament

• GET /api/tournament - Get the active tournament and its point overrides
• POST /api/tournament - Create and activate a tournament
• PUT /api/tournament - End a tournament
• POST /api/tournament/[id]/actions - Save point overrides for a tournament

Security Note

The application has no authentication — anyone who can reach it on the network can manage matches and scores. Run it only on a trusted LAN.

Troubleshooting

Common Issues

1. Port Already in Use

   • Change ports in docker-compose.yml (default: 3000 for app, 5432 for database)
   • Or stop other services using these ports

2. Docker Permission Issues

   sudo docker-compose up -d
   

3. Database Connection Issues

   # Restart the services
   docker-compose down
   docker-compose up -d
   

4. Application Not Loading

   # Check logs
   docker-compose logs -f app
   
   # Rebuild containers
   docker-compose down
   docker-compose up -d --build
   

5. Volume/Mount Issues

   docker-compose down -v
   docker-compose up -d --build
   

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

This project is licensed under the MIT License.