PlayRise

What is PlayRise?

PlayRise is a mobile-first sports management platform that brings automated ladder rankings, private challenges, and club administration to racket sports clubs.

Core Value Proposition

Traditional sports ladders are managed manually — spreadsheets, whiteboards, or disconnected apps. PlayRise automates the entire process: when a player joins a ladder, rounds are generated automatically; when a match result is submitted, rankings update instantly, positions swap, and the next round is ready — with zero intervention from the club owner.

Supported Sports

Each sport has a dedicated color theme and emoji identifier used consistently across the UI for quick recognition.

Platform

• iOS and Android — single codebase via React Native / Expo
• Dark UI — designed for low-light sports environments
• Portrait orientation — mobile-first layout throughout
• Deep linking — scheme playrise:// for invite links

Who Uses PlayRise?

PlayRise has two distinct user types, each with a completely separate navigation experience, dashboard, and set of capabilities.

Role Detection

User type is determined at signup and stored in the profiles.is_club_owner boolean column. This flag is set from the signup form where users self-identify, and is passed through Supabase auth metadata to the auto-created profile record.

Club Roles (within a Club)

Challenge Status Flow

Built On

PlayRise uses a modern, production-ready stack with minimal infrastructure overhead — the backend is fully managed by Supabase.

Frontend

Backend (Supabase)

Key Architectural Choices

Structure & Navigation

The app is built around Expo Router's file-based routing system, with separate tab groups for each user type.

Navigation Tree

app/
├── _layout.tsx              ← Root: checks auth → routes to correct group
│
├── (auth)/                  ← Unauthenticated users
│   ├── login.tsx
│   └── signup.tsx
│
├── onboarding/
│   └── club.tsx             ← 6-step wizard, first-time club owners only
│
├── (tabs)/                  ← Players (bottom tab bar)
│   ├── _layout.tsx             Tabs: My Ladders | My Matches | Browse Clubs | Profile
│   ├── index.tsx               My Ladders
│   ├── challenges.tsx          My Matches (Ladder / Private / History)
│   ├── clubs.tsx               Browse Clubs
│   └── profile.tsx             Player Profile
│
├── (owner-tabs)/            ← Club Owners (separate bottom tab bar)
│   ├── _layout.tsx             Tabs: Members | Ladders | Tournaments | Club
│   ├── index.tsx               Members Management
│   ├── ladders.tsx             Ladders Management
│   ├── tournaments.tsx         Tournaments
│   └── club.tsx                Club Settings
│
├── club/[id].tsx            ← Shared stack screens
├── club/create.tsx
├── club/manage.tsx
├── ladder/[id].tsx
├── ladder/create.tsx
├── ladder/manage.tsx
├── challenge/new.tsx
└── match/new.tsx

Auth & Routing Logic

The root _layout.tsx manages routing decisions using three pieces of state from AuthContext:

Project File Structure

Data Model

PlayRise uses 8 PostgreSQL tables plus 1 view. All tables have Row Level Security enabled.

Entity Relationship Overview

auth.users (Supabase)
    │
    └─ profiles (1:1)
         │
         ├─ club_members (N) ─── clubs
         │                          │
         │                          ├─ ladders (N)
         │                          │       │
         │                          │       └─ ladder_entries (N) ← position, wins, losses, points
         │                          │               │
         │                          │               └─ matches (N) ← winner_id, score, played_at
         │                          │
         │                          └─ tournaments (N)
         │                                  │
         │                                  └─ tournament_entries (N)
         │
         └─ challenges (N) ─── ladders

Table: profiles

Table: clubs

Table: ladders

Table: ladder_entries

Table: matches

Table: challenges

View: clubs_with_member_count

A computed view joining clubs with an aggregated member count. Used in the Browse Clubs screen to avoid N+1 queries.

SELECT c.*, COUNT(cm.id)::int AS member_count
FROM clubs c
LEFT JOIN club_members cm ON cm.club_id = c.id
GROUP BY c.id;

How the Ranking System Works

The ladder system is fully automated. No admin action is needed once a ladder is created and players start joining.

Ranking Model

Each ladder maintains an ordered list of players. Position 1 is the best. Every player has:

• Position — their current rank on the ladder (integer, unique per ladder)
• Wins / Losses — cumulative match record
• Points — earned at +20 per win

Visual Example

Round Generation

A "round" is a set of matches pairing all players in the ladder. Rounds are generated automatically — never manually by an admin.

A new round is generated when:

1. A player joins the ladder — a PostgreSQL trigger (auto_round_on_join) fires on ladder_entries INSERT and calls generate_ladder_round().
2. The last pending match in a round gets a result — after record_match_result() updates the match, it calls generate_ladder_round(). Since there are now zero pending matches, a fresh round is created.

Position Swap Logic

When a lower-ranked player beats a higher-ranked player, they swap positions. For example, if #4 beats #3, they exchange positions: the former #4 becomes #3, and the former #3 drops to #4.

This uses a 3-step swap inside a single transaction to respect the UNIQUE(ladder_id, position) constraint:

-- Step 1: Set winner to temp position -1
UPDATE ladder_entries SET position = -1
WHERE ladder_id = p_ladder_id AND user_id = winner;

-- Step 2: Move loser to winner's old position
UPDATE ladder_entries SET position = old_winner_pos
WHERE ladder_id = p_ladder_id AND user_id = loser;

-- Step 3: Set winner to loser's old position
UPDATE ladder_entries SET position = old_loser_pos
WHERE ladder_id = p_ladder_id AND user_id = winner;

Points System

Auto-Enrollment

When a match result is submitted via record_match_result(), the function checks if either player is already enrolled in the ladder. If not, they are automatically added at the bottom of the rankings. This allows challenge results to feed into the ladder even if the players joined through a private challenge rather than direct ladder enrollment.

Feature Walkthrough: Player

Everything a player can do from signup through daily use.

1. Signup & Login

Players sign up by choosing the "I am a Player" role, entering a username, full name, email, and password. A Supabase auth trigger automatically creates a profile record. On login, the session is stored securely via expo-secure-store.

2. Browse Clubs

The Browse Clubs tab lists all public clubs. If the player grants location permission, clubs are sorted by GPS distance (Haversine formula calculated client-side). Each club card shows the name, location, member count, and supported sports.

3. Join a Club

From a club detail page, non-members see a "Become a Member" button that inserts a club_members row with role member. Alternatively, players can use a club's invite code during signup.

4. Join a Ladder

From the ladder detail page, the player taps "Join Ladder." This inserts a ladder_entries row at position N+1 (bottom of the ladder). The auto_round_on_join trigger immediately fires and runs generate_ladder_round() — if conditions are met, a new round of matches is generated and the player will see their scheduled match in My Matches.

5. My Matches — Three Tabs

6. Send a Challenge

From any club detail page, every member sees a ⚡ button next to other members. Tapping opens /challenge/new, which shows the opponent's name, lets the player select which ladder the challenge is for (all active club ladders), add an optional message, and propose a date. The challenge expires automatically after 7 days.

7. Submit a Match Result

The match result screen shows both players as selectable cards. The player taps the winner, then optionally enters the score set-by-set using +/- controls (e.g., Set 1: 6–3, Set 2: 4–6, Set 3: 6–4). On Submit, a single RPC call to record_match_result() handles everything atomically.

8. Player Profile

The profile tab shows aggregate stats (total wins, losses, win rate, ladder count), all enrolled ladders with position and sport, recent match history, and a sign-out button.

Feature Walkthrough: Club Owner

Club owners have a dedicated admin interface separate from the player experience.

1. Club Onboarding Wizard

First-time owners go through a 6-step animated wizard before accessing the dashboard:

2. Members Tab

Lists all members across all clubs the owner administers. For each member:

• Avatar with initials, full name, username, role badge
• Toggle between Admin ↔ Member role
• Remove from club button (with confirmation)
• Cannot modify own account from this screen

3. Ladders Tab

Lists all ladders grouped by club. For each ladder:

• Sport color dot, name, player count
• Active/inactive toggle switch (inline)
• Settings button → /ladder/manage
• Delete button (with confirmation)
• "New Ladder" button at top

4. Ladder Management Screen

Reached via the Settings button on a ladder card. Contains:

• Settings card: Edit name, sport, active toggle, season start/end → Save
• Players section: Full list with position, W-L-Pts-Win%, remove button per player
• Reset Rankings: Re-sorts all players by win rate (then points) and reassigns positions 1-N
• Info banner: Explains rounds are auto-generated (no manual trigger needed)

5. Tournaments Tab

Manage bracket tournaments separate from the ladder system:

• Create tournaments with name, sport, max players, club assignment
• View enrollment counts (X / max players)
• Status badges: Upcoming / Active / Completed
• Delete tournaments with confirmation

6. Club Settings Tab

• Edit Info: Change club name, description, location
• Invite Code: View, copy, and regenerate the 8-character invite code
• Member count stat
• Danger Zone: Delete club (destructive, with confirmation)
• Sign Out

Every Screen

A complete catalog of all 20+ screens in the app, their routes, and what they do.

Authentication Screens

Player Screens

Owner Screens

Shared Stack Screens

PostgreSQL Functions & RLS

All critical business logic runs inside the database as SECURITY DEFINER functions, ensuring atomicity and bypassing per-user RLS where cross-user writes are needed.

record_match_result() — Core RPC

The most important function in the system. Called from the app after a match. Handles everything in a single atomic transaction.

Execution steps (all in one transaction):

1. Create or update the matches row with winner, score, played_at = now()
2. Mark the challenge as completed (if challenge_id provided)
3. Auto-enroll any player not yet in the ladder at the bottom position
4. Increment winner's wins by 1 and points by 20
5. Increment loser's losses by 1
6. If winner's position > loser's position: perform the 3-step position swap
7. Call generate_ladder_round(p_ladder_id) to create next round if ready
8. Return the match UUID

generate_ladder_round() — Auto Round Creator

Pairs adjacent-ranked players and inserts scheduled match rows.

FUNCTION generate_ladder_round(p_ladder_id uuid) RETURNS int
LANGUAGE plpgsql SECURITY DEFINER

-- Returns 0 if there are already unplayed non-challenge matches
-- Otherwise pairs #1 vs #2, #3 vs #4, ... and returns count created

handle_new_user() — Signup Trigger

Fires automatically after every new row in auth.users. Reads raw_user_meta_data (set during supabase.auth.signUp()) and creates the corresponding profiles row with username, full_name, is_club_owner, etc.

trg_auto_round_on_join() — Join Trigger

Fires after every INSERT on ladder_entries. Calls generate_ladder_round() for the new player's ladder. If at least 2 players are present and no pending matches exist, a new round is created immediately.

Row Level Security (RLS)

All tables have RLS enabled. The key policies:

End-to-End Journeys

Step-by-step walkthroughs of every major action in the app.

Flow 1: New Player Signup to First Match

Flow 2: Club Owner Onboarding

Flow 3: Private Challenge

Flow 4: Position Swap (Lower-Ranked Wins)

Visual Identity

PlayRise uses a dark UI with a teal primary color, consistent across both iOS and Android.

Color Palette

Sport Theming

UI Conventions

• Dark-first: All screens use the dark color palette; no light mode.
• Rounded corners: Cards use borderRadius: 16, buttons borderRadius: 14, inputs borderRadius: 12.
• Initials avatars: No photo uploads on core screens — player names are represented by 2-letter initials in circular badges.
• Trophy icons: Position 1–3 in standings use a trophy icon; positions 4+ use the numeric rank.
• Badge counters: Tab bars show numeric badges (orange) for pending actions (pending matches, pending challenges).
• Safe back navigation: All stack screens use router.canGoBack() ? router.back() : router.replace(tabRoot) to prevent navigation dead-ends.
• Icon library: Ionicons from @expo/vector-icons throughout.

Supabase API

All API calls are made through the Supabase JS client. No custom REST endpoints.

Supabase Client Config

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
import * as SecureStore from 'expo-secure-store'

const supabase = createClient(
  process.env.EXPO_PUBLIC_SUPABASE_URL,
  process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY,
  {
    auth: {
      storage: SecureStore,        // encrypted token storage
      autoRefreshToken: true,
      persistSession: true,
      detectSessionInUrl: false,
    }
  }
)

Key RPC Calls

// Submit a match result (core function)
await supabase.rpc('record_match_result', {
  p_match_id:     matchId ?? null,
  p_ladder_id:    ladderId,
  p_player1_id:   player1Id,
  p_player2_id:   player2Id,
  p_winner_id:    winnerId,
  p_score:        "6-3, 4-6, 6-4",
  p_challenge_id: challengeId ?? null,
})

// Manually trigger round generation
await supabase.rpc('generate_ladder_round', {
  p_ladder_id: ladderId
})

// Seed mock players for testing
await supabase.rpc('seed_mock_players', {
  p_club_id: clubId
})

Common Table Queries

// Fetch ladder with club and entries
supabase.from('ladders')
  .select('*, club:clubs(id, name)')
  .eq('id', ladderId)
  .single()

// Fetch standings (entries with profile)
supabase.from('ladder_entries')
  .select('*, profile:profiles(username, full_name)')
  .eq('ladder_id', ladderId)
  .order('position')

// Fetch scheduled (unplayed) ladder matches
supabase.from('matches')
  .select('*, player1:profiles!matches_player1_id_fkey(...), ...')
  .eq('ladder_id', ladderId)
  .is('winner_id', null)

// Fetch user's pending challenges (received)
supabase.from('challenges')
  .select('*, challenger:profiles!challenger_id(*), ladder:ladders(*)')
  .eq('challenged_id', userId)
  .eq('status', 'pending')

Auth Calls

// Sign up
supabase.auth.signUp({
  email, password,
  options: { data: { username, full_name, is_club_owner } }
})

// Sign in
supabase.auth.signInWithPassword({ email, password })

// Sign out
supabase.auth.signOut()

// Get current session
supabase.auth.getSession()

// Listen for auth changes
supabase.auth.onAuthStateChange((event, session) => { ... })

Getting Started

How to set up and run the PlayRise project locally.

Prerequisites

• Node.js 18+ and npm/yarn/bun
• Expo CLI: npm install -g @expo/cli
• Expo Go app on a physical device, or iOS Simulator / Android Emulator
• A Supabase project (free tier works fine)

Installation

# Clone the repository
git clone <repo-url> PlayRise
cd PlayRise

# Install dependencies
npm install

# Create environment file
cp .env.example .env

Environment Variables

# .env
EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

Database Setup

Run each migration file in order in the Supabase SQL editor:

supabase/migrations/
  20260315000000_initial_schema.sql      ← Run first
  20260316000000_owner_features.sql
  20260316000001_fix_owner_trigger.sql
  20260316000002_clubs_location.sql
  20260316000003_scheduled_matches.sql
  20260316000004_mock_players.sql
  20260316000005_auto_rounds.sql
  20260316000006_record_match_result.sql ← Run last

Running the App

# Start Expo dev server
npx expo start

# Options:
npx expo start --ios        # iOS Simulator
npx expo start --android    # Android Emulator
# Or scan QR code with Expo Go on device

Seeding Test Data

-- Run in Supabase SQL editor after getting a club ID
SELECT seed_mock_players('your-club-uuid-here');
-- Creates 8 mock players, enrolls them in all active ladders,
-- generates past matches for realistic data

Migration Notes

Project Scripts