TTAnalysis Table Tennis App Guide

Provides comprehensive guidance for working with the TTAnalysis codebase - a table tennis match analysis web application that enables point-by-point tracking, shot type classification, and performance statistics.

What This Skill Does

This skill equips AI agents with deep contextual knowledge of the TTAnalysis project structure, development workflow, database schema, and architectural patterns. Use this when working on features, debugging issues, or maintaining the TTAnalysis table tennis analysis application.

Project Architecture

TTAnalysis is a full-stack web application with the following technology stack:

**Frontend:**

React with TypeScript for type-safe component development

React Router for client-side navigation

Custom CSS for styling (no external UI frameworks)

Vite as the build tool and development server

**Backend:**

Supabase Backend-as-a-Service providing:

- PostgreSQL database

- Authentication system

- Storage capabilities

- Row-level security policies

**Mobile-First Design:**

Optimized for courtside usage during live matches

Responsive layout for tablets and phones

Development Workflow

Starting the Development Environment

1. **Recommended: Full stack with Supabase**

```bash

./start-dev.sh

```

This script handles:

- Starting local Supabase services (PostgreSQL, Auth, etc.)

- Creating a test user if one doesn't exist

- Starting the Vite development server

2. **Frontend only (without Supabase)**

```bash

npm run dev

```

Common Development Commands

```bash

Install dependencies

npm install

Apply new migrations to database

IMPORTANT: NEVER use supabase db reset

supabase db push

Build for production

npm run build

Lint the codebase

npm run lint

Preview production build

npm run preview

Promote a user to admin

Requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .env

npm run promote-admin [email protected]

```

Environment Variables

Required environment variables for Supabase integration:

`VITE_SUPABASE_URL` - URL for the Supabase instance

`VITE_SUPABASE_ANON_KEY` - Anonymous API key for Supabase

`SUPABASE_SERVICE_ROLE_KEY` - Service role key (for admin operations)

Database Schema

The PostgreSQL database contains the following core tables:

Users

`id` - Primary key

`email` - User email address

`name` - User display name

`preferences` - User settings and preferences

Shot Categories

`id` - Primary key

`name` - Category name

`display_order` - Sort order for UI

Shots

`id` - Primary key

`category_id` - Foreign key to shot_categories

`name` - Shot identifier

`display_name` - User-facing name

`description` - Shot description

`display_order` - Sort order within category

Matches

`id` - Primary key

`user_id` - Foreign key to users

`opponent_name` - Opponent's name

`date` - Match date

`match_score` - Final match score

`notes` - Match notes

`initial_server` - Who served first

Sets

`id` - Primary key

`match_id` - Foreign key to matches

`set_number` - Set number in match

`score` - Set score string

`player_score` - User's score

`opponent_score` - Opponent's score

Points

`id` - Primary key

`set_id` - Foreign key to sets

`point_number` - Point number in set

`winner` - Who won the point ('player' or 'opponent')

`winning_shot_id` - Foreign key to shots (winning shot)

`winning_hand` - Hand used for winning shot

`other_shot_id` - Foreign key to shots (other shot in rally)

`other_hand` - Hand used for other shot

`notes` - Point notes

Code Organization

```

/src

├── components/ # Reusable UI components

│ ├── Layout # App layout wrapper

│ ├── PlayerPanel # Player score display

│ └── ShotSelector # Shot type selection UI

├── pages/ # Main application screens

├── lib/ # Utilities and external clients

│ └── supabase # Supabase client configuration

├── types/ # TypeScript type definitions

└── styles/ # Global CSS and stylesheets

/supabase

└── migrations/ # Database migration files

/docs # Project documentation

```

Key Features & Data Flow

Match Creation

User creates match with opponent name and date

Match stored in local state and Supabase

Sets initial server

Point Recording Flow

1. Select winning player (user or opponent)

2. Select winning shot type from categorized list

3. Select other shot type (shot that didn't win the point)

4. Record point and automatically update scores

5. Track server changes (every 2 points per table tennis rules)

Set Completion

First player to 11 points wins (must win by 2)

Automated tracking of set scores

Automatic progression to next set

Match Completion

Summary statistics displayed

Performance analysis and visualization

Shot type frequency and success rates

Important Constraints

1. **Never use `supabase db reset`** - Always use `supabase db push` to apply migrations

2. **Row-level security** - All database queries respect Supabase RLS policies

3. **Shot IDs from database** - Point recording uses shot IDs fetched from the shots table, not hardcoded values

4. **Server rotation** - Server changes every 2 points following table tennis rules

5. **Mobile-first** - UI must remain usable on small screens for courtside usage

Development Best Practices

1. **Type Safety**: Leverage TypeScript definitions in `/src/types` for all database entities

2. **Component Reusability**: Extract common UI patterns into `/src/components`

3. **Database Migrations**: Store all schema changes in `/supabase/migrations` with descriptive names

4. **Environment Configuration**: Never commit `.env` files; use `.env.example` as template

5. **Testing**: Use the test user created by `start-dev.sh` for development testing

When Working on TTAnalysis

Check `/docs` for additional project documentation

Review existing migrations before creating new ones

Test point recording flow thoroughly (it's the core feature)

Verify RLS policies when adding database queries

Ensure mobile responsiveness for any UI changes

Follow the established component structure in `/src/components`

Example Workflows

Adding a New Shot Type

1. Create migration in `/supabase/migrations`

2. Add to appropriate shot category

3. Set display_order for UI positioning

4. Run `supabase db push`

5. Test in ShotSelector component

Creating a New Analysis View

1. Create component in `/src/pages`

2. Add route in React Router configuration

3. Query match/point data via Supabase client

4. Render statistics using existing styling patterns

5. Test with various match data scenarios

Implementing Admin Features

1. Use `promote-admin` script to grant admin role

2. Check user role in RLS policies

3. Add admin-only UI elements

4. Secure admin API endpoints

TTAnalysis Table Tennis App Guide

TTAnalysis Table Tennis App Guide

What This Skill Does

Project Architecture

Development Workflow

Starting the Development Environment

Common Development Commands

Install dependencies

Apply new migrations to database

IMPORTANT: NEVER use supabase db reset

Build for production

Lint the codebase

Preview production build

Promote a user to admin

Requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .env

Environment Variables

Database Schema

Users

Shot Categories

Shots

Matches

Sets

Points

Code Organization

Key Features & Data Flow

Match Creation

Point Recording Flow

Set Completion

Match Completion

Important Constraints

Development Best Practices

When Working on TTAnalysis

Example Workflows

Adding a New Shot Type

Creating a New Analysis View

Implementing Admin Features

Reviews (0)