Matching & Discovery
Smart assessment-based trainer matching, the Explore page for content discovery, and trainer profile browsing. The system connects clients with compatible trainers and surfaces relevant programs through curated collections, challenges, and search.
Overview
The Matching & Discovery feature is the primary way clients find trainers and programs on My Trainer Connect. It combines algorithmic matching with manual exploration to provide both personalized recommendations and free-form browsing. The system uses data from client onboarding assessments (goals, experience, preferences, budget, location) to calculate match percentages against trainer profiles.
The Smart Matching system presents a multi-question assessment modal for clients who want targeted recommendations. Responses are compared against trainer specialties, pricing, training formats, location, and experience to generate a match percentage displayed on each trainer lead. These results are saved for ongoing recommendations and surfaced in the trainer's feed as new leads.
The Explore page is a rich discovery surface featuring a search bar with category selector, curated collections (staff picks, trending, new releases, custom bundles), time-limited fitness challenges with prizes and participant tracking, a top trainers carousel, featured programs, and a category explorer. It also promotes the AI Coach and Smart Match features via banner CTAs.
User Stories
Client Stories
As a client, I want to take a matching assessment so that I'm connected with trainers who fit my goals, budget, and preferences.
As a client, I want to see match percentages on trainer profiles so that I can quickly identify the best fits.
As a client, I want to browse the Explore page to discover trending programs, challenges, and top trainers.
As a client, I want to search for trainers and programs by keyword and category so that I can find specific content.
As a client, I want to join fitness challenges with prizes so that I have extra motivation and community engagement.
As a client, I want to view detailed trainer profiles (bio, specialties, pricing, rating, reviews) so that I can make informed decisions.
Trainer Stories
As a trainer, I want to receive leads with match percentages so that I can prioritize clients who are the best fit.
As a trainer, I want my profile to appear in search and collections so that I can be discovered by potential clients.
As a trainer, I want to be featured in the top trainers carousel so that I get maximum visibility on the Explore page.
Admin Stories
As an admin, I want to create curated collections of programs so that I can highlight quality content for clients.
As an admin, I want to create and manage challenges with prizes and time limits so that I can drive engagement.
Smart Matching
Assessment Factors
Goals Alignment
Match client goals (weight loss, muscle building, etc.) against trainer specialties
Experience Level
Client experience (beginner/intermediate/advanced) vs. trainer focus areas
Training Format
Online, in-person, or hybrid preference compatibility
Budget Range
Client budget aligned with trainer pricing tiers
Location
Geographic proximity for in-person training (PostGIS)
Gender Preference
Client preference for trainer gender (male/female/no preference)
Explore Page Sections
Search & Category Selector
Unified search bar with dropdown category filter. Search across trainers, programs, and challenges.
Collections
Curated program bundles: staff picks, trending, new releases, custom themed collections. Admin-managed.
Challenges
Time-limited fitness challenges with prizes. Participant tracking, progress updates, and leaderboards.
Top Trainers Carousel
Horizontally scrollable carousel of highest-rated trainers with rating, review count, and connect buttons.
Featured Programs
Highlighted programs from the marketplace with hero cards showing pricing, difficulty, ratings, and enrollment counts.
AI Coach & Smart Match CTAs
Banner CTAs promoting the AI Coach chat and Smart Match assessment for personalized recommendations.
Data Model
| Table | Key Columns | Description |
|---|---|---|
| trainer_profiles | specialties[], rating_avg, review_count, is_verified, location (PostGIS), search_vector (tsvector) | Trainer data used for matching and search. Full-text search via tsvector column. |
| client_profiles | goals[], experience_level, training_format, budget_min, budget_max, gender_preference, location | Client assessment data used as input to matching algorithm. |
| trainer_connections | id, trainer_id, client_id, status, match_percentage, created_at | Connection records between trainers and clients with match score. |
| connection_requests | id, from_user_id, to_user_id, status, message, match_percentage, created_at | Pending connection requests. Status: pending, accepted, rejected, blocked. |
| challenges | id, title, description, start_date, end_date, prize_description, participant_count, cover_image_url, created_by | Time-limited fitness challenges with prizes and participant tracking. |
| collections | id, title, description, type, cover_image_url, is_featured, created_by | Curated program bundles. Types: staff_picks, trending, new_releases, custom. |
| collection_items | id, collection_id, program_id, sort_order | Programs within a collection, ordered by sort_order. |
| trainer_reviews | id, trainer_id, client_id, rating, review_text, created_at | Client reviews and 5-star ratings for trainers. |
Trainer Profile Display
When clients browse trainers, the following profile data is displayed:
Professional summary and coaching philosophy
Tags like Weight Loss, HIIT, Yoga, Strength
City, state for in-person availability
Online rate, in-person rate, monthly coaching
Years of experience (0-50)
Average rating (1-5 stars)
Total number of client reviews
Admin-approved verification status
Screens & Routes
| Route | File | Description |
|---|---|---|
| /explore | src/routes/_authed/_onboarded/_client/explore.tsx | Client explore page — search, collections, challenges, top trainers, featured programs |
| /connections | src/routes/_authed/_onboarded/_client/connections.tsx | Client connections list — connected trainers with profile previews |
| /leads | src/routes/_authed/_onboarded/_trainer/leads.tsx | Trainer leads page — incoming client leads with match percentages |
| /clients | src/routes/_authed/_onboarded/_trainer/clients.tsx | Trainer clients list — active client management |
Acceptance Criteria
Smart Matching
Explore Page
Trainer Profiles
Connections
API Surface
The matching API is planned but not yet implemented. The current UI uses mock data from src/mocks/trainers.ts.
Planned Server Functions
POST runSmartMatch — Calculate matches based on assessment responses
GET getMatchedTrainers — Fetch trainers sorted by match percentage
GET searchTrainers — Full-text search with filters (specialty, location, price)
GET getTrainerPublicProfile — Public trainer profile for client viewing
GET getCollections — Curated program collections
GET getChallenges — Active and upcoming challenges
POST joinChallenge — Enroll in a challenge
GET getFeaturedPrograms — Admin-featured marketplace programs
GET getTopTrainers — Highest-rated trainers for carousel
POST sendConnectionRequest — Request connection with trainer
POST respondToConnectionRequest — Accept/reject/block a request
Current Status
- Explore page UI with mock data
- Trainer cards with ratings and specialties
- Connections page UI (client)
- Leads page UI (trainer)
- Clients page UI (trainer)
- Mock trainer data
- PostGIS location columns on profiles
- Full-text search vector on trainer_profiles
- Database schema for connections, challenges, collections
- Trainer search server functions
- Matching algorithm implementation
- Assessment modal
- Match percentage calculation
- Connection request flow (API)
- Challenges system
- Collections management
- Trainer public profile pages
- Featured programs curation
- Category explorer