Skip to content

replit.md

Latest commit

 

History

History
155 lines (123 loc) · 7.75 KB

replit.md

File metadata and controls

155 lines (123 loc) · 7.75 KB

Racket Advisor - Table Tennis Equipment Recommendation System

Overview

Racket Advisor is a web application that helps table tennis players find their optimal equipment setup (blade + rubbers) using a patented dichotomous analysis algorithm. The system analyzes a player's style through a comprehensive questionnaire and generates personalized recommendations based on four key dimensions: Speed/Control, Hardness/Flexibility, Dynamics/Predictability, and Spin/Flat Attack.

The application uses a weighted scoring system to match player profiles with equipment characteristics, calculating both absolute ratings and synergy scores to recommend the best blade and rubber combinations.

Important Concept: Racket Advisor is designed for equipment refinement and optimization from current inventory, NOT for initial equipment selection. Users should have existing equipment to get the most value from personalized recommendations.

User Preferences

Preferred communication style: Simple, everyday language.

Recent Changes (November 10, 2025)

Phase 1: Navigation & Information Enhancement

  1. Enhanced Navigation System (AppLayout.tsx)

    • Added breadcrumbs support with optional BreadcrumbItem[] prop
    • Added "Назад" (Back) button using browser history
    • Added "На главную" (Home) button for quick navigation to /
    • Navigation automatically appears on all non-home pages (location !== "/")
    • ThemeToggle position adapts based on navigation presence
    • All navigation elements have proper data-testid attributes for testing

  2. Home Page Enhancements

    • Added "О концепции сервиса" Alert section explaining service concept
    • Clarifies that Racket Advisor is for equipment refinement, not initial selection
    • Changed bottom info cards from 2-column to 3-column grid
    • Added clickable Glossary card link (data-testid: card-glossary-link)

  3. New Glossary Page (/glossary)

    • Comprehensive terminology reference with 22+ terms
    • Organized into 8 categories: Характеристики, Оборудование, Компоненты, Материалы, Система подбора, Техника, Стили игры, Классы оборудования
    • Accordion UI for collapsible term definitions
    • Each term includes: definition, category, and optional related terms
    • Related terms displayed as clickable badges for cross-reference
    • All interactive elements properly instrumented with data-testid
    • Category icons and term counts for easy navigation

  4. Questionnaire Navigation Consistency

    • Added QuestionnaireNav component to all 4 questionnaire screens
    • Ensures consistent navigation experience across all pages
    • Includes back button, home button, and theme toggle on every screen

System Architecture

Frontend Architecture

Framework & Build System:

  • React 18 with TypeScript for type safety
  • Vite as the build tool and development server
  • Wouter for client-side routing (lightweight alternative to React Router)
  • TanStack React Query for server state management and API caching

UI Component Strategy:

  • Shadcn/ui component library (Radix UI primitives + Tailwind CSS)
  • Material Design 3 principles with data visualization focus
  • New York style variant for components
  • Custom design system with Inter (primary) and JetBrains Mono (numerical data) fonts

State Management:

  • Local component state for questionnaire flow
  • LocalStorage for persisting recommendation results between page navigations
  • React Query for API data fetching and caching

Key Application Flow:

  1. Home page introduces the service
  2. Questionnaire page with adaptive multi-step form:
    • Equipment questionnaire (4 dichotomous questions)
    • Current equipment input (optional: blade, forehand/backhand rubbers with autocomplete search)
    • Equipment feedback screen (conditional: 6-dimensional feedback if current equipment provided)
    • Complaints selection screen
  3. Results page displaying:
    • Player profile visualization (radar chart with dichotomous dimensions)
    • Current equipment card (shows user's existing setup and feedback adjustments)
    • Top-3 recommendations with comparison badges showing deltas vs current equipment
    • Detailed comparison table
  4. Modal detail views for individual recommendations

Backend Architecture

Server Framework:

  • Express.js with TypeScript
  • ESM module system throughout
  • Development mode uses Vite middleware for HMR
  • Production build uses esbuild for server bundling

API Design:

  • POST /api/recommendations - accepts player answers with optional current equipment and feedback
  • GET /api/equipment/search - autocomplete search for blades and rubbers by brand/name
  • Calculates player profile using dichotomous analysis
  • Applies equipment feedback corrections to profile if provided
  • Generates equipment recommendations with weighted scoring
  • Returns comprehensive response including player profile, current equipment, recommendations, and calculation time

Calculation Engine:

  • Dichotomous profile calculation based on questionnaire answers
  • Profile adjustment engine (applyEquipmentFeedback) for personalization based on current equipment feedback
  • Weighted fit score algorithm: -SUM(ABS(Blade[i] - Player[i]) * Weight[i])
  • Weights: Control=8, Flexibility=8, Predictability=9, Spin=10
  • Synergy calculation for rubber-blade compatibility (60% synergy, 40% absolute rating)
  • Equipment comparison using normalized brand+name slugs for delta detection

Data Storage:

  • In-memory storage implementation (MemStorage class)
  • Equipment database (blades and rubbers) stored as static TypeScript data
  • No database currently used - all equipment data is code-based
  • Designed with IStorage interface for future database integration

Data Models & Validation

Schema Architecture:

  • Zod schemas for runtime type validation and TypeScript type inference
  • Shared schema definitions between client and server (shared/schema.ts)
  • Drizzle-zod integration prepared for future database implementation

Core Data Types:

  • DichotomousProfile: Four dimensions rated -5 to +5
  • Blade: Equipment with brand, name, and dichotomous profile
  • RubberProfile: Control, spin, hardness, grip rated 0-10
  • Rubber: Rubber with brand, name, and profile characteristics
  • PlayerAnswers: Questionnaire responses with optional current equipment and feedback
  • CurrentEquipment: User's existing blade/rubbers with IDs (brand+name format) and optional feedback
  • EquipmentFeedback: 6-dimensional feedback (speed, control, hardness, flexibility, predictability, spin) rated as too_low/optimal/too_high
  • Recommendation: Complete setup with blade, forehand/backhand rubbers, scores, and justification

External Dependencies

UI & Styling:

  • Tailwind CSS for utility-first styling with custom design tokens
  • Radix UI for accessible, unstyled component primitives
  • Chart.js (via CDN) for radar chart visualizations
  • Google Fonts CDN for Inter and JetBrains Mono typefaces
  • Lucide React for consistent iconography

Development Tools:

  • TypeScript for static type checking across the entire stack
  • ESLint and type checking via tsc
  • Replit-specific plugins for development experience (cartographer, dev banner, runtime error overlay)

Database Preparation:

  • Drizzle ORM configured for PostgreSQL (via @neondatabase/serverless)
  • Drizzle Kit for schema migrations
  • Configuration ready but database not actively used (equipment data is static)

Form & Validation:

  • React Hook Form with Hookform Resolvers for form state management
  • Zod for schema validation
  • Integration ready for complex form validation in questionnaire

Session Management:

  • connect-pg-simple configured for PostgreSQL session storage
  • Not currently active (no user authentication implemented)