FitPass - Fitness Class Booking Platform

🚧 Project Status

This project is currently a work in progress.

Planned / In Progress

• 🤖 AI-powered assistant (Vercel AI SDK)
• 🏢 Advanced admin management via Sanity App SDK
• 📍 Activities & Venues dynamic pages
• 🚀 Production deployment

✨ Features

For Users

• 🗺️ Location-Based Search - Find classes within your preferred radius using advanced geographic filtering
• 🔍 Smart Filtering - Filter by category, venue, instructor, subscription tier, and more
• 📅 Calendar View - Visualize your bookings in an interactive calendar
• 🤖 AI Assistant - Chat with an AI assistant to find classes and get recommendations
• 📱 Responsive Design - Works seamlessly on mobile, tablet, and desktop
• ⚡ Real-Time Updates - See new classes and availability changes instantly
• 🎫 Subscription Tiers - Basic, Performance, and Champion tiers with different booking limits
• ✅ Attendance Tracking - Confirm attendance after classes
• 🗺️ Interactive Maps - See venue locations on an interactive map

For Admins

• 📝 Content Management - Manage activities, sessions, and venues through Sanity Studio
• 🖼️ Image Management - Upload and manage images with automatic optimization
• 📊 Session Management - Create and schedule class sessions with capacity management
• 🏢 Venue Management - Add venues with addresses and amenities
• 🔄 Publish/Unpublish - Draft and publish workflow for content

🚀 Tech Stack

Frontend

• Next.js 16 - React framework with App Router and Server Components
• React 19 - UI library with React Compiler
• TypeScript - Type-safe development
• Tailwind CSS 4 - Utility-first styling
• Radix UI - Accessible component primitives
• Leaflet - Interactive maps
• Zustand - Lightweight state management

Backend & Data

• Sanity CMS - Headless content management system
• GROQ - Query language for Sanity
• Sanity Live - Real-time content updates
• Next.js Server Actions - Server-side mutations

Authentication & Billing

• Clerk - Authentication and user management
• Clerk Billing - Subscription tier management

AI & Chat

• Vercel AI SDK 6 - AI agent framework
• OpenAI GPT-4o-mini - Language model
• Tool Calling - Database query tools for AI

Development Tools

• Biome - Fast linter and formatter
• TypeScript - Static type checking
• Sanity Typegen - Auto-generated types

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 20.x or higher
• pnpm (recommended) or npm/yarn
• Git

🛠️ Installation

1. Clone the repository

   git clone https://github.com/yourusername/class-booking-app.git
   cd class-booking-app

2. Install dependencies

   pnpm install
   # or
   npm install

3. Set up environment variables

   Create a .env.local file in the root directory:

   # Sanity CMS
   NEXT_PUBLIC_SANITY_PROJECT_ID=your_project_id
   NEXT_PUBLIC_SANITY_DATASET=production
   NEXT_PUBLIC_SANITY_API_VERSION=2025-12-15
   SANITY_API_READ_TOKEN=your_read_token
   SANITY_API_WRITE_TOKEN=your_write_token
   
   # Clerk Authentication
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key
   CLERK_SECRET_KEY=your_secret_key
   
   # OpenAI (for AI chat)
   OPENAI_API_KEY=your_openai_api_key
   
   # Optional: Mapbox (for address search in admin)
   NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_token

4. Generate TypeScript types

   pnpm typegen

5. Run the development server

   pnpm dev

6. Open your browser

   Navigate to http://localhost:3000

🔧 Available Scripts

# Development
pnpm dev          # Start development server

# Production
pnpm build        # Build for production
pnpm start        # Start production server

# Code Quality
pnpm lint         # Run linter
pnpm format       # Format code

# Type Generation
pnpm typegen      # Generate Sanity TypeScript types

📁 Project Structure

class-booking-app/
├── app/                          # Next.js App Router
│   ├── (app)/                    # User-facing routes
│   │   ├── classes/              # Browse and book classes
│   │   ├── bookings/              # Manage bookings
│   │   ├── profile/              # User profile & preferences
│   │   ├── onboarding/           # First-time setup
│   │   └── upgrade/              # Subscription management
│   ├── (admin)/                  # Admin panel routes
│   │   └── admin/                # Content management
│   ├── api/                      # API routes
│   │   └── chat/                 # AI chat endpoint
│   └── studio/                   # Sanity Studio (CMS)
│
├── components/                   # React components
│   ├── app/                      # User-facing components
│   ├── admin/                    # Admin panel components
│   └── ui/                       # Reusable UI primitives
│
├── lib/                          # Business logic
│   ├── actions/                  # Server actions
│   ├── ai/                       # AI agent & tools
│   ├── constants/                # App constants
│   ├── hooks/                    # Custom React hooks
│   ├── store/                    # Zustand stores
│   └── utils/                    # Utility functions
│
└── sanity/                       # Sanity CMS configuration
    ├── lib/                      # Sanity client & queries
    └── schemaTypes/              # Content schemas

🔑 Environment Variables

Required Variables

Variable	Description	Where to Get It
NEXT_PUBLIC_SANITY_PROJECT_ID	Sanity project ID	Sanity Dashboard
NEXT_PUBLIC_SANITY_DATASET	Sanity dataset name	Usually production or development
SANITY_API_READ_TOKEN	Sanity read token	Sanity Dashboard → API → Tokens
SANITY_API_WRITE_TOKEN	Sanity write token	Sanity Dashboard → API → Tokens
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Clerk publishable key	Clerk Dashboard
CLERK_SECRET_KEY	Clerk secret key	Clerk Dashboard → API Keys
OPENAI_API_KEY	OpenAI API key	OpenAI Platform

Optional Variables

Variable	Description
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN	Mapbox token for address search in admin panel

🎯 Key Features Explained

Geographic Search Optimization

The app uses a two-step geographic filtering system for fast, accurate location-based search:

1. Bounding Box (Database-level): Fast rectangular filter reduces 100k+ sessions to ~100-500
2. Haversine Formula (Client-side): Precise circular distance calculation for accuracy

This approach makes location-based search 10-100x faster than naive implementations.

Real-Time Updates

Content updates automatically when:

• New sessions are added
• Bookings are created/cancelled
• Availability changes
• Content is published in Sanity Studio

Powered by Sanity Live for seamless real-time synchronization.

AI-Powered Search

Chat with an AI assistant to:

• Search for classes by natural language
• Get personalized recommendations
• Check your bookings
• Find venues near you

The AI uses tool calling to query the database in real-time.

Subscription Tiers

Three subscription tiers with different benefits:

• Basic: 5 classes/month, Basic-tier classes only
• Performance: 12 classes/month, Basic + Performance classes
• Champion: Unlimited classes, All classes

Higher tiers can access lower-tier classes (hierarchical access).

🗺️ Sanity Studio

Access the content management interface at /studio:

1. Start the dev server: pnpm dev
2. Navigate to http://localhost:3000/studio
3. Sign in with your Sanity account
4. Manage activities, sessions, venues, and more

🚢 Deployment

Deploy to Vercel (Recommended)

1. Push to GitHub

   git push origin main

2. Import to Vercel

   • Go to vercel.com
   • Click "New Project"
   • Import your repository

3. Add Environment Variables

   • Add all required environment variables in Vercel dashboard
   • Deploy

4. Configure Sanity CORS

   • In Sanity Dashboard → API → CORS Origins
   • Add your Vercel domain: https://your-app.vercel.app

Build Locally

pnpm build
pnpm start

🧪 Development

Adding New Features

1. Create Sanity Schema (if needed)

   • Add schema in sanity/schemaTypes/
   • Run pnpm typegen to generate types

2. Create GROQ Query

   • Add query in sanity/lib/queries/
   • Use defineQuery for type safety

3. Create Server Action (if needed)

   • Add action in lib/actions/
   • Use "use server" directive

4. Create Components

   • Add components in components/
   • Use Server Components by default
   • Only use Client Components when needed

Code Style

• Linting: Run pnpm lint before committing
• Formatting: Code is auto-formatted with Biome
• Type Safety: TypeScript is required, no any types

📚 Documentation

• Comprehensive Technical Walkthrough - Complete technical documentation covering architecture, implementation details, design decisions, and code examples

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request