Roundup Games

Tabletop and Board Game Platform

Roundup Games is a modern web platform for managing games, teams, and events. Built with TanStack Start and deployed on Netlify.

Tech Stack

• Framework: TanStack Start (React meta-framework)
• Authentication: Better Auth
• Database: Drizzle ORM with PostgreSQL
• Styling: Tailwind CSS v4 + shadcn/ui
• Build Tool: Vite 7
• Environment Validation: @t3-oss/env-core with Zod
• Testing: Vitest with coverage
• Deployment: Netlify

Prerequisites

• Node.js: v20.19.0+ (required for Vite 7)
• pnpm: v10+
• PostgreSQL: Database instance

Environment Variables

Environment variables are validated at startup using Zod schemas. Create a .env file in the project root:

# Database (required)
DATABASE_URL=postgresql://user:password@localhost:5432/solstice

# Application (only required in development)
VITE_BASE_URL=http://localhost:5173

# Auth (required for production)
BETTER_AUTH_SECRET=your-secret-key

# OAuth Providers (optional)
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Feature Flags (optional)
VITE_ENABLE_ANALYTICS=false
VITE_ENABLE_SENTRY=false
VITE_POSTHOG_KEY=your_posthog_key
VITE_SENTRY_DSN=your_sentry_dsn

Environment Validation: The app validates all environment variables at startup and provides clear error messages for missing or invalid values. See src/lib/env.server.ts and src/lib/env.client.ts for the validation schemas.

Project Structure

• src/routes/ - File-based routing (pages and API endpoints)
• src/lib/auth/ - Better Auth configuration and functions
• src/lib/db/ - Drizzle database setup and schemas
• src/lib/env.server.ts - Server-side environment validation
• src/lib/env.client.ts - Client-side environment validation
• src/components/ui/ - shadcn/ui components
• src/shared/ - Shared utilities and hooks

Development

1. Install dependencies:

   pnpm install

2. Set up the database:

   pnpm db push

3. Generate auth schemas:

   pnpm auth:generate

4. Run the development server:

   pnpm dev

Documentation

• CLAUDE.md - Guidelines for Claude Code AI assistant
• TanStack Start Best Practices - Server functions and type safety patterns
• Database Connections - Connection pooling and usage patterns
• Project Brief - High-level project overview
• Development Backlog - Feature implementation roadmap

Available Scripts

Development

• pnpm dev - Start development server with Netlify Dev
• pnpm build - Build for production
• pnpm start - Start production server

Code Quality

• pnpm lint - Run ESLint
• pnpm check-types - Type checking with TypeScript
• pnpm format - Format code with Prettier

Testing

• pnpm test - Run tests with Vitest
• pnpm test:ui - Run tests with UI
• pnpm test:coverage - Run tests with coverage
• pnpm test:watch - Run tests in watch mode

Database

• pnpm db - Run Drizzle Kit database commands
• pnpm db:generate - Generate database migrations
• pnpm db:migrate - Run database migrations
• pnpm db:studio - Open Drizzle Studio

Utilities

• pnpm auth:generate - Generate auth schema from config
• pnpm auth:secret - Generate new auth secret
• pnpm ui - Add shadcn/ui components
• pnpm deps - Check for dependency updates with taze

Dependency Management

Use taze to keep dependencies up to date:

# Check for updates interactively
pnpm dlx taze@latest --interactive --group

# Or use the shortcut
pnpm deps

Taze automatically detects your package manager and provides a safe, interactive way to update dependencies.

Deployment

The application is automatically deployed to Netlify:

• Production: Pushes to main branch trigger production deployments
• Preview: Pull requests get automatic preview deployments

CI/CD

GitHub Actions workflows handle:

• Continuous Integration: Linting, type checking, and testing on Node.js 20
• Deploy Previews: Automatic Netlify preview deployments for pull requests
• Code Coverage: Test coverage reports uploaded to Codecov

Required GitHub Secrets

Configure these secrets in your GitHub repository settings:

• DATABASE_URL - PostgreSQL connection string for CI tests
• VITE_BASE_URL - Base URL for the application (not needed in production - Netlify provides URL automatically)
• BETTER_AUTH_SECRET - Auth secret key (generate with pnpm auth:secret locally)
• NETLIFY_AUTH_TOKEN - Netlify authentication token
• NETLIFY_SITE_ID - Netlify site ID
• CODECOV_TOKEN - Codecov upload token (optional)
• DISCORD_CLIENT_ID - GitHub OAuth client ID
• DISCORD_CLIENT_SECRET - GitHub OAuth client secret
• GOOGLE_CLIENT_ID - Google OAuth client ID
• GOOGLE_CLIENT_SECRET - Google OAuth client secret

Overview and Purpose

The Roundup Games platform streamlines management – initially serving Roundup Games and eventually adaptable to other organizations. The platform enables tabletop and board game enthusiasts to connect and organize game sessions and events.

Key Features:

• Member Registration & Management: User accounts, profiles, waivers, and annual memberships
• Team Setup & Roster Management: Team creation, player invitations, and roster management
• Event Creation & Registration: Tournament/league management with team/individual registration
• Payments & Finance: Integration with a payment platform for membership and event fees
• Role-Based Access Control: Admin, Team Lead, and Player permission layers
• Communication & Notifications: Email confirmations and announcements