Tango - Customer Booking Interface

Tango is the customer-facing booking application that enables users to discover services, view availability, and make reservations with merchants.

Overview

Port: 5174
Purpose: Customer booking and reservation management
Authentication: Optional (guest booking supported)
Tech Stack: React 19, TanStack Router, TanStack Query, Tailwind CSS 4

Key Features

Service Discovery

Browse merchant services with detailed descriptions and pricing

Real-Time Availability

View available time slots in real-time with calendar interface

Guest Booking

Make reservations without creating an account

Booking Management

View, modify, and cancel reservations

Multi-Phase Services

Book complex services with multiple phases and steps

Location Information

Interactive maps showing merchant locations

Technology Stack

Core Dependencies

From frontend/apps/tango/package.json: Tango relies primarily on shared dependencies from the root workspace:

React 19.2.3 - Latest React version
TanStack Router 1.147.1 - File-based routing
TanStack Query 5.90.16 - Server state management
Tailwind CSS 4.1.18 - Styling
mapbox-gl 3.17.0 - Interactive maps (from root package.json)
react-day-picker 9.13.0 - Date selection component

Shared Packages

@reservations/components - Reusable UI components
@reservations/lib - Utilities and hooks
@reservations/assets - Icons and images (BackArrowIcon, etc.)

Application Structure

Route Organization

Overview
Route Parameters
Route Details

Tango uses a merchant-scoped routing structure:

routes/
├── __root.jsx                    # Root layout
├── index.jsx                     # Landing page
├── login.jsx                     # Customer login
├── signup/                       # Customer registration
└── m/$merchantName/              # Merchant-scoped routes
    ├── index.jsx                 # Merchant profile
    ├── services/$serviceId/      # Service details
    ├── booking/                  # Booking flow
    └── cancel/$bookingId/        # Cancellation flow

All merchant-specific functionality is scoped under /m/:merchantName to support multi-tenancy.

Dynamic route parameters:

$merchantName - Unique merchant identifier
$serviceId - Service ID for service details
$bookingId - Booking ID for cancellation

Example URLs:

/m/salon-luxe - Merchant profile
/m/salon-luxe/services/123 - Service details
/m/salon-luxe/booking - Booking flow
/m/salon-luxe/cancel/456 - Cancel booking

Complete route structure:

m/$merchantName/
├── index.jsx                     # Merchant landing page
├── -components/
│   ├── MapboxMap.jsx            # Location map
│   ├── ReservationSection.jsx   # Booking preview
│   ├── ServiceCategoryItem.jsx  # Category display
│   └── ServiceItem.jsx          # Service card
├── services/$serviceId/
│   ├── index.jsx                # Service detail page
│   └── -components/
│       ├── PhaseItem.jsx        # Multi-phase service steps
│       └── DropDownBusinessHours.jsx
├── booking/
│   ├── index.jsx                # Booking creation
│   ├── completed.jsx            # Confirmation page
│   └── -components/
│       └── AvailableTimeSection.jsx
└── cancel/$bookingId/
    ├── index.jsx                # Cancellation form
    └── completed.jsx            # Cancellation confirmation

Customer Journey

User Authentication

Tango supports both authenticated and guest users:

Guest Flow
Login
Registration

Users can book without an account:

Browse merchant services
Select service and time
Enter contact information
Receive booking confirmation via email
Use booking link for management

Route: /signup/Multi-step registration process:

EmailForm component:

Email validation
Duplicate check
Verification code sent

Personal Info

NameForm component:

First and last name
Optional middle name

Phone

PhoneNumberForm component:

Phone number with validation
SMS verification option

Password

PasswordForm component:

Secure password creation
Password strength indicator
Confirmation field

Complete

SubmissionCompleted component:

Account created confirmation
Email verification prompt
Redirect to booking or profile

Booking Flow

Merchant Discovery

Route: /m/$merchantName/index.jsx Merchant profile page with:

Business Information

Merchant name and description
Business hours display
Contact information
Location with interactive map (MapboxMap)

Service Catalog

ServiceCategoryItem components:

Services organized by category
ServiceItem cards with:
- Service name and description
- Duration and pricing
- Quick booking button

Recent Reservations

ReservationSection component:

Upcoming bookings (for logged-in users)
Booking history preview
Quick actions (modify, cancel)

Service Details

Route: /m/$merchantName/services/$serviceId/index.jsx Detailed service information:

Service Overview
- Full description
- Pricing details
- Duration and capacity
- Employee information
Multi-Phase Services
- PhaseItem components for each phase
- Phase descriptions and durations
- Prerequisites and dependencies
- Total service time calculation
Business Hours
- DropDownBusinessHours component
- Weekly schedule display
- Special hours and holidays
- Availability indicators
Booking Action
- Prominent “Book Now” button
- Redirects to booking flow with service pre-selected

Booking Creation

Route: /m/$merchantName/booking/index.jsx Interactive booking creation:

Service Selection

If not pre-selected:

Browse available services
View pricing and duration
Select service to continue

Date Selection

SmallCalendar component from @reservations/components:

Month view calendar
Available dates highlighted
Blocked dates shown in gray
Navigate between months

Time Selection

AvailableTimeSection component:

Fetches real-time availability
Displays available time slots
Shows time slot duration
Indicates employee (if applicable)
Handles multi-phase scheduling

Customer Information

For guests:

Name input fields
Email (required for confirmation)
Phone number
Optional notes/requests

For logged-in users:

Pre-filled contact info
Option to update details
Add special requests

Review & Confirm

Summary of booking details
Service, date, time confirmation
Customer information review
Final pricing display
Terms and conditions
Submit booking button

Booking Confirmation

Route: /m/$merchantName/booking/completed.jsx Post-booking confirmation page:

Booking success message
Booking reference number
Service details summary
Date and time confirmation
Add to calendar options
Email confirmation notice
Cancellation policy information
Link to manage booking

Availability Engine

The booking flow uses TanStack Query to fetch availability:

// From booking/index.jsx
async function fetchHours(merchantName, locationId, serviceId, start, end) {
  const response = await fetch(
    `/api/v1/merchants/${merchantName}/locations/${locationId}/services/${serviceId}/availability?start=${start}&end=${end}`
  );
  // Returns available time slots
}

Features:

Real-time availability checking
Handles multi-phase services
Employee-specific availability
Buffer time calculation
Blocked time periods
Business hours compliance

Booking Management

Cancellation Flow

Route: /m/$merchantName/cancel/$bookingId/

Cancellation Request

index.jsx - Cancellation form:

Booking details display
Cancellation policy reminder
Reason for cancellation (optional)
Refund information (if applicable)
Confirm cancellation button

Cancellation Confirmation

completed.jsx - Confirmation page:

Cancellation success message
Refund details (if applicable)
Email confirmation notice
Option to book again

Key Components

Merchant Page Components

MapboxMap - Interactive location map using Mapbox GL
ReservationSection - User’s upcoming and past reservations
ServiceCategoryItem - Service category display with services
ServiceItem - Individual service card with booking action

Service Detail Components

PhaseItem - Multi-phase service step display
DropDownBusinessHours - Expandable business hours schedule

Booking Components

AvailableTimeSection - Real-time time slot availability
SmallCalendar - Date picker from @reservations/components
Uses shared components: Button, Loading, ServerError, Textarea

EmailForm - Email validation and verification
NameForm - Name input fields
PhoneNumberForm - Phone number with validation
PasswordForm - Secure password creation
SubmissionCompleted - Registration success

Shared Components

From @reservations/components:

Button - Primary action buttons
Loading - Loading states
ServerError - Error handling
SmallCalendar - Date selection
Textarea - Multi-line text input

Shared Assets

From @reservations/assets:

BackArrowIcon - Navigation back button

Data Fetching

Tango uses TanStack Query with the following patterns:

import { useQuery, queryOptions, keepPreviousData } from '@tanstack/react-query';

// Example from booking/index.jsx
const { data, isLoading, isError } = useQuery({
  queryKey: ['availability', merchantName, serviceId, start, end],
  queryFn: () => fetchHours(merchantName, locationId, serviceId, start, end),
  placeholderData: keepPreviousData,
});

Key Patterns:

Query keys with dependencies
Placeholder data for smooth transitions
Error handling with ServerError component
Loading states with Loading component
Automatic refetching and caching

API Integration

Endpoints Used

GET /api/v1/merchants/:merchantName - Merchant profile
GET /api/v1/merchants/:merchantName/services - Service listing
GET /api/v1/merchants/:merchantName/services/:serviceId - Service details
GET /api/v1/merchants/:merchantName/locations/:locationId/services/:serviceId/availability - Time slot availability
POST /api/v1/bookings - Create booking
DELETE /api/v1/bookings/:bookingId - Cancel booking
GET /api/v1/customers/bookings - User booking history

Error Handling

if (isError) {
  return <ServerError />;
}

All API errors display the shared ServerError component from @reservations/components.

Utilities from @reservations/lib

Tango uses several utilities from the shared lib package:

formatToDateString - Format dates for display
GetDayPickerWindow - Calculate date picker range
getDisplayPrice - Format prices for display
invalidateLocalStorageAuth - Handle auth token expiration

Development

Running Tango

# Start development server on port 5174
npm run dev-tango

# Build for production
npm run build-tango

Development Features

Hot module replacement (HMR)
API proxy to backend at /api
Local domain support (.reservations.local)
React DevTools integration
TanStack Query DevTools for debugging queries

Testing Flows

Guest Booking
Authenticated Booking
Cancellation

Navigate to /m/[merchant-name]
Select a service
Choose date and time
Enter guest information
Confirm booking

Login at /login
Navigate to merchant
Select service
Choose date and time
Review pre-filled info
Confirm booking

Access booking via email link or account
Navigate to /m/[merchant]/cancel/[booking-id]
Review booking details
Confirm cancellation

User Experience

Mobile-First Design

Tango is optimized for mobile devices:

Touch-friendly interface
Responsive layouts with Tailwind CSS
Optimized calendar interactions
Fast loading times
Minimal data usage

Performance Optimizations

Code splitting with TanStack Router
Query caching with TanStack Query
Optimistic UI updates
Lazy loading of components
Image optimization

Accessibility

Semantic HTML structure
ARIA labels on interactive elements
Keyboard navigation support
Screen reader friendly
High contrast text

Frontend Overview

Learn about the frontend monorepo architecture

Jabulani Dashboard

Explore the merchant dashboard application

Getting Started

Setup & Deployment

Core Features

Backend

Frontend

​Overview

​Key Features

Service Discovery

Real-Time Availability

Guest Booking

Booking Management

Multi-Phase Services

Location Information

​Technology Stack

​Core Dependencies

​Shared Packages

​Application Structure

​Route Organization

​Customer Journey

​User Authentication

​Booking Flow

​Merchant Discovery

​Service Details

​Booking Creation

​Booking Confirmation

​Availability Engine

​Booking Management

​Cancellation Flow

​Key Components

​Merchant Page Components

​Service Detail Components

​Booking Components

​Signup Components

​Shared Components

​Shared Assets

​Data Fetching

​API Integration

​Endpoints Used

​Error Handling

​Utilities from @reservations/lib

​Development

​Running Tango

​Development Features

​Testing Flows

​User Experience

​Mobile-First Design

​Performance Optimizations

​Accessibility

​Related Resources

Frontend Overview

Jabulani Dashboard

Build docs developers (and LLMs) love

Overview

Key Features

Technology Stack

Core Dependencies

Shared Packages

Application Structure

Route Organization

Customer Journey

User Authentication

Booking Flow

Merchant Discovery

Service Details

Booking Creation

Booking Confirmation

Availability Engine

Booking Management

Cancellation Flow

Key Components

Merchant Page Components

Service Detail Components

Booking Components

Signup Components

Shared Components

Shared Assets

Data Fetching

API Integration

Endpoints Used

Error Handling

Utilities from @reservations/lib

Development

Running Tango

Development Features

Testing Flows

User Experience

Mobile-First Design

Performance Optimizations

Accessibility

Related Resources