WagerBabe - Sports Betting Platform

A modern, full-stack sports betting platform built with FastAPI, React, and Supabase.

🏗️ Architecture Overview

WagerBabe follows a clean, modular architecture with clear separation between client and backend:

wagerbabe/
├── client/          # Next.js React application
├── backend/           # FastAPI application
├── docs/              # Documentation and guides
└── README.md          # This file

Technology Stack

• Backend: FastAPI with Python
• client: Next.js 15 with React 19
• Authentication: Supabase Auth
• Database: PostgreSQL via Supabase
• UI Components: shadcn/ui with Tailwind CSS
• State Management: React Context API
• Styling: Custom theming system with automatic propagation

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.8+
• Supabase account (for when you're ready to set up authentication)

1. Clone and Setup

git clone <repository-url>
cd wagerbabe

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file
cp .env.example .env
# Edit .env with your Supabase credentials when ready

# Run the server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

3. client Setup

cd client

# Install dependencies
npm install

# Copy environment file
cp .env.local.example .env.local
# Edit .env.local with your Supabase credentials when ready

# Run the development server
npm run dev

4. Database Setup (When Ready)

1. Create a new Supabase project
2. The SQL migrations are available in docs/supabase-migrations.sql for future use
3. Update your environment files with the Supabase credentials

📁 Project Structure

Backend Structure

backend/
├── app/
│   ├── api/v1/           # API routes
│   │   ├── endpoints/    # Individual endpoint files
│   │   └── api.py        # Main API router
│   ├── core/             # Core configuration
│   │   ├── config.py     # Settings and configuration
│   │   └── supabase.py   # Supabase client setup
│   ├── models/           # Pydantic models
│   ├── services/         # Business logic
│   ├── utils/            # Utility functions
│   └── main.py           # FastAPI application entry point
├── tests/                # Test files
└── requirements.txt      # Python dependencies

client Structure

client/
├── src/
│   ├── app/              # Next.js app directory
│   ├── components/       # React components
│   │   ├── ui/           # shadcn/ui components
│   │   ├── base/         # Custom base components
│   │   └── theme-provider.tsx
│   ├── contexts/         # React Context providers
│   ├── lib/              # Utility libraries
│   │   ├── utils.ts      # General utilities
│   │   ├── theme.ts      # Theme configuration
│   │   ├── supabase.ts   # Supabase client
│   │   └── supabase-types.ts # TypeScript types
│   └── styles/           # Global styles
├── public/               # Static assets
└── package.json          # Node.js dependencies

🎨 Styling System

WagerBabe implements a sophisticated theming system where base component styles automatically propagate to composite components.

Key Features

1. Automatic Style Propagation: Changes to base components automatically apply to all composite components
2. Sports Betting Specific Colors: Pre-defined color schemes for betting statuses (win, loss, pending, live)
3. Context-Aware Theming: Different themes for sportsbook, casino, and poker sections
4. Dark/Light Mode Support: Built-in theme switching with system preference detection

Theme Configuration

The theming system is configured in client/src/lib/theme.ts:

// Sports betting specific colors
export const sportsTheme = {
  win: { light: "oklch(0.7 0.15 142)", DEFAULT: "oklch(0.6 0.18 142)" },
  loss: { light: "oklch(0.7 0.15 27)", DEFAULT: "oklch(0.6 0.18 27)" },
  pending: { light: "oklch(0.8 0.1 60)", DEFAULT: "oklch(0.7 0.15 60)" },
  live: { light: "oklch(0.8 0.15 15)", DEFAULT: "oklch(0.7 0.2 15)" }
}

Using the Theme System

1. Base Components: Located in client/src/components/base/

   • BettingCard: Themed card component with betting-specific variants
   • OddsButton: Automatically styled based on odds values
   • StatusBadge: Color-coded status indicators

2. CSS Utilities: Pre-defined classes in globals.css

   .odds-positive { @apply text-win font-semibold; }
   .status-live { @apply bg-live text-live-foreground animate-pulse; }

3. Theme Provider: Wrap your app with theme providers

   <ThemeProvider defaultTheme="system" defaultBettingContext="sportsbook">
     <YourApp />
   </ThemeProvider>

🔧 State Management

WagerBabe uses React Context API for state management with three main contexts:

1. AuthContext

Manages user authentication state, login/logout, and user profile data.

const { user, signIn, signOut, loading } = useAuth()

2. BettingContext

Handles betting slip, odds selection, and bet placement.

const { state, addSelection, removeSelection, placeBet } = useBetting()

3. ThemeContext

Manages theme switching and betting context (sportsbook/casino/poker).

const { theme, setTheme, bettingContext, setBettingContext } = useTheme()

🔐 Authentication

Authentication is handled through Supabase Auth with the following features:

• Email/password authentication
• Automatic session management
• Protected routes
• User profile management
• Password reset functionality

Usage Example

import { useAuth } from '@/contexts'

function LoginForm() {
  const { signIn, loading } = useAuth()
  
  const handleSubmit = async (email: string, password: string) => {
    const { error } = await signIn(email, password)
    if (error) {
      // Handle error
    }
  }
}

📊 Database Schema

The application uses PostgreSQL through Supabase with the following main tables:

• profiles: User profile information and balance
• bets: Betting history and current bets
• transactions: Financial transaction history

See docs/supabase-migrations.sql for the complete schema.

🧪 Testing

Backend Testing

cd backend
pytest

client Testing

cd client
npm test

🚀 Deployment

Backend Deployment

The FastAPI backend can be deployed to any platform that supports Python applications:

• Heroku
• Railway
• DigitalOcean App Platform
• AWS Lambda (with Mangum)

client Deployment

The Next.js client can be deployed to:

• Vercel (recommended)
• Netlify
• AWS Amplify
• Any platform supporting Node.js

📝 Development Guidelines

1. Component Development: Always extend base components rather than creating new ones from scratch
2. Styling: Use the theme system utilities instead of hardcoded colors
3. State Management: Use appropriate context providers for different types of state
4. Type Safety: Leverage TypeScript types for Supabase operations
5. Testing: Write tests for all new components and API endpoints

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following the established patterns
4. Write tests for new functionality
5. Submit a pull request

📄 License

This project is licensed under the MIT License.