Skip to content

README.md

Latest commit

 

History

History
284 lines (214 loc) · 7.24 KB

README.md

File metadata and controls

284 lines (214 loc) · 7.24 KB

MatchDay Monorepo

A comprehensive sports team management platform with separate player and admin applications, built on a shared codebase.

📦 Monorepo Structure

matchday/
├── apps/
│   ├── player/          # Player-facing Next.js app (port 3000)
│   ├── admin/           # Admin Next.js app (port 3001)
├── packages/
│   ├── database/        # Shared database types and schema
│   ├── services/        # Shared business logic services
│   ├── auth/            # Authentication utilities
│   └── shared/          # Common utilities and helpers
├── supabase/            # Database migrations and config
└── pnpm-workspace.yaml  # Workspace configuration

✨ Features

  • Team Management: Create and manage teams with detailed player rosters and statistics
  • League Discovery: Browse and join leagues for organized play
  • Player Dashboard: Comprehensive player profiles with performance analytics
  • Match Recording: Post-match score recording and statistics tracking
  • Achievement System: Player achievements and performance recognition
  • Global Leaderboards: Track top performers across leagues and teams
  • User Authentication: Secure authentication with user profiles and preferences
  • Responsive Design: Optimized for desktop and mobile devices

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • pnpm 8+ (npm install -g pnpm)
  • Supabase account

Installation

# Install all dependencies
pnpm install

# Start player app (port 3000)
pnpm dev:player

# Start admin app (port 3001)
pnpm dev:admin

# Run both apps simultaneously
pnpm dev

📱 Applications

Player App (apps/player/)

Player-facing features:

  • Team management and player rosters
  • League discovery and joining
  • Match tracking and live scoring
  • Player dashboards and statistics
  • Achievement system
  • Global leaderboards

Port: 3000 Environment: .env.local with NEXT_PUBLIC_SITE_URL=http://localhost:3000

Admin App (apps/admin/)

Admin-facing features:

  • League management and creation
  • Team join request approval
  • Match scheduling and management
  • User role administration
  • System oversight and analytics

Port: 3001 Environment: .env.local with NEXT_PUBLIC_SITE_URL=http://localhost:3001

📚 Shared Packages

@matchday/database

Database types and schema definitions generated from Supabase. Provides type-safe access to:

  • User profiles
  • Leagues and seasons
  • Teams and team members
  • Matches and statistics

@matchday/services

Shared business logic services:

  • League service
  • Team service
  • Match service
  • Season service
  • Player service
  • User service
  • Stats service
  • Analytics service
  • Achievement service

@matchday/auth

Authentication and authorization utilities:

  • JWT validation
  • Role-based access control
  • Session management

@matchday/shared

Common utilities and helpers:

  • Tailwind class utilities (cn)
  • Date formatters
  • Environment validation
  • Constants and configurations

🛠 Development Commands

# Development
pnpm dev              # Run both apps in parallel
pnpm dev:player       # Run player app only
pnpm dev:admin        # Run admin app only

# Building
pnpm build            # Build all apps and packages
pnpm build:player     # Build player app
pnpm build:admin      # Build admin app
pnpm build:packages   # Build shared packages only

# Code Quality
pnpm lint             # Lint both apps
pnpm type-check       # Type-check both apps
pnpm test             # Run player app tests
pnpm format           # Format all code with Prettier

# Cleaning
pnpm clean            # Remove all node_modules and build artifacts

🗄️ Database

Both apps share the same Supabase PostgreSQL database.

Migrations

Database migrations are located in supabase/migrations/ and managed centrally.

# Apply migrations
npx supabase db push

# Create new migration
npx supabase migration new migration_name

Schema Updates

When database schema changes:

  1. Update migrations in supabase/migrations/
  2. Regenerate types in packages/database/src/database.types.ts
  3. Update service layer if needed

🔐 Environment Setup

Both apps require environment variables for Supabase connection.

Player App (.env.local)

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Admin App (.env.local)

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
NEXT_PUBLIC_SITE_URL=http://localhost:3002

🏗️ Tech Stack

  • Framework: Next.js 15 with App Router
  • Frontend: React 19, TypeScript 5
  • Styling: Tailwind CSS v4
  • Database: Supabase (PostgreSQL)
  • Authentication: Supabase Auth
  • State Management: React Query (TanStack Query)
  • Monorepo: pnpm workspaces
  • Testing: Jest, React Testing Library

📝 Development Guidelines

Adding Shared Code

  1. Database Types: Add to packages/database/src/database.types.ts
  2. Services: Add to packages/services/src/
  3. Auth Logic: Add to packages/auth/src/
  4. Utilities: Add to packages/shared/src/

Creating New Apps

# Create new app directory
mkdir apps/new-app

# Add to workspace
# Update pnpm-workspace.yaml (already includes apps/*)

# Install workspace dependencies
cd apps/new-app
pnpm add @matchday/database@workspace:*
pnpm add @matchday/services@workspace:*

Importing Shared Packages

// In any app
import { Database } from '@matchday/database';
import { LeagueService } from '@matchday/services';
import { validateSession } from '@matchday/auth';
import { cn, formatDate } from '@matchday/shared';

🚢 Deployment

Vercel (Recommended)

Both apps can be deployed separately to Vercel:

# Deploy player app
cd apps/player
vercel

# Deploy admin app
cd apps/admin
vercel --prod

Configure environment variables in Vercel dashboard for each app.

Other Platforms

The monorepo is compatible with:

  • Netlify
  • Railway
  • AWS Amplify
  • DigitalOcean App Platform

🔒 Security

🚨 CRITICAL: If you've leaked Supabase keys, follow the KEY_ROTATION_CHECKLIST.md immediately.

For security best practices, RLS policies, and incident response procedures, see SECURITY.md.

Quick Security Tips

  • ✅ Keep .env.local files OUT of git (already in .gitignore)
  • ✅ Use LOCAL Supabase for development (not production)
  • ✅ Environment variables are validated on app startup
  • ✅ All database tables have Row Level Security (RLS) enabled
  • ⚠️ Never commit SUPABASE_SERVICE_ROLE_KEY - it's server-side only

🤝 Contributing

  1. Create a feature branch: git checkout -b feature/your-feature
  2. Make your changes
  3. Test both apps: pnpm test && pnpm type-check
  4. Commit: git commit -m 'feat: add feature'
  5. Push: git push origin feature/your-feature
  6. Open a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For issues and questions:

  • Check existing issues on GitHub
  • Create a new issue with detailed description
  • Include error messages and reproduction steps