MatchPlay Pro AI - Complete App Blueprint
Comprehensive technical documentation for rebuilding the entire application
Application Purpose
MatchPlay Pro AI is a comprehensive performance analytics and tracking platform for racket sports players (Table Tennis, Tennis, Badminton, Squash, Pickleball). It provides match tracking, opponent intelligence, coaching resources, and AI-powered insights to help players improve their game.
Technology Stack
- Framework: React 18.2.0
- Routing: React Router DOM 6.26.0
- State Management: @tanstack/react-query 5.84.1
- Styling: Tailwind CSS + shadcn/ui components
- Animations: Framer Motion 11.16.4
- Forms: React Hook Form 7.54.2
- Charts: Recharts 2.15.4
- Icons: Lucide React 0.475.0
- Date Handling: date-fns 3.6.0
- Markdown: React Markdown 9.0.1
- Maps: React Leaflet 4.2.1
- Drag & Drop: @hello-pangea/dnd 17.0.0
- Video: React Quill 2.0.0
- Platform: Base44 BaaS
- SDK: @base44/sdk 0.8.3
- Functions Runtime: Deno Deploy
- Database: Base44 Entity System (PostgreSQL)
- Authentication: Base44 Auth (Email/Password)
- File Storage: Supabase Storage
- Payments: Stripe Integration
- AI: Base44 InvokeLLM Integration
- Email: Base44 SendEmail Integration
Application Structure
project-root/ ├── entities/ # Data models (JSON schemas) │ ├── User.json # Built-in user entity │ ├── Match.json │ ├── Opponent.json │ ├── Fixture.json │ ├── Coach.json │ ├── Partner.json │ └── ... (30+ entities) │ ├── pages/ # Route pages (flat structure) │ ├── Home.jsx │ ├── Dashboard.jsx │ ├── Matches.jsx │ ├── Opponents.jsx │ ├── CoachingHub.jsx │ └── ... (50+ pages) │ ├── components/ # Reusable components (can have subfolders) │ ├── ui/ # shadcn/ui components │ ├── dashboard/ # Dashboard widgets │ ├── admin/ # Admin components │ ├── coach/ # Coaching components │ ├── partners/ # Partner widgets │ ├── sport/ # Sport-specific logic │ ├── language/ # Multi-language support │ └── ... (100+ components) │ ├── functions/ # Backend functions (Deno) │ ├── createCheckoutSession.js │ ├── stripeWebhook.js │ ├── importFixtures.js │ └── ... (10+ functions) │ ├── agents/ # AI agents configuration │ └── user_assistant.json │ ├── Layout.jsx # App layout wrapper └── globals.css # Global styles
Key Architecture Principles
1. Multi-Sport Support
Sport configuration system (sportConfig) provides sport-specific terminology, colors, scoring rules, playing styles, and equipment options. Context provider manages current sport selection.
2. Multi-Language Support
Language context provider with translation function (t). Supports English, Spanish, French, German, Italian, Portuguese, Dutch, Russian, Chinese, Japanese, Korean.
3. Role-Based Access Control
User roles (admin, user). Entity-level Row Level Security (RLS). Coach-specific features gated by coach profile existence. Premium features controlled by subscription status.
4. Component-First Design
Small, focused, reusable components. Dashboard widgets are independent components. Forms use React Hook Form. UI components from shadcn/ui library.
Authentication & Authorization
- • Use AuthGuard component to protect routes requiring authentication
- • Check user.role === "admin" for admin-only features
- • Entity RLS rules enforce created_by filters automatically
- • Coach features gated by checking Coach entity existence for user_email
- • Premium features check subscription status via Subscription entity
Data Fetching Pattern
- • Use @tanstack/react-query for data fetching with caching
- • Base44 SDK methods: list(), filter(), create(), update(), delete()
- • Always filter by sport when fetching sport-specific data
- • Use invalidateQueries after mutations to refresh data
UI/UX Patterns
- • Use shadcn/ui components for consistency
- • Framer Motion for animations (initial, animate, whileInView)
- • Sport-specific colors via sportConfig.color
- • Responsive design with Tailwind's md:, lg: breakpoints
- • Loading skeletons during data fetching
- • Toast notifications for user feedback
Performance Optimization
- • Lazy load heavy components
- • Paginate large lists (matches, opponents)
- • Cache query results with React Query
- • Optimize images (use appropriate sizes, lazy loading)
- • Minimize re-renders with React.memo where appropriate
Deployment Checklist
- • Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in environment
- • Configure Stripe webhook endpoint URL
- • Test payment flow in Stripe test mode first
- • Verify all backend functions deploy successfully
- • Test RLS rules for each entity
- • Verify sport context persists across sessions
- • Test multi-language switching
- • Ensure PWA manifest and service worker configured