booking-management

---

name: booking-management description: Guide for managing train bookings, IRCTC accounts, and booking records in the TrainTrack application

This skill provides guidance for working with the booking management system in TrainTrack, including booking CRUD operations, IRCTC account management, and booking completion records.

Booking Management

Core Concepts

Booking Status Types:

• pending - Bookings that are not yet completed
• completed - Bookings that have been successfully completed
• cancelled - Bookings that were cancelled

Train Classes: sleeper, 3ac, 2ac, 1ac

Booking Data Structure:

• Source and destination stations
• Journey date (stored as Firestore Timestamp, convert to ISO string)
• Passenger details array (name, age, gender, berth preference)
• Train number and class
• IRCTC account reference
• Status tracking with reasons

Working with Bookings

When implementing booking-related features:

1. Type Definitions: Use types from src/types/booking.ts

   • BookingStatus, TrainClass, Passenger, Booking interfaces

2. Custom Hooks: Use existing hooks in src/hooks/useBookings.ts

   • React Query for data fetching and caching
   • Real-time updates with Firestore listeners
   • Infinite scroll for completed bookings

3. Date Handling: Always convert Firestore Timestamps to ISO strings:

   CopyjourneyDate: booking.journeyDate?.toDate?.()?.toISOString() || booking.journeyDate
   

4. Form Handling: Use React Hook Form + Zod validation

   • See BookingForm.tsx for patterns
   • Dynamic passenger array management
   • Status badge components for visual feedback

IRCTC Account Management

Account Features:

• Store IRCTC credentials and wallet information
• Track account status and balance
• Link accounts to bookings

Working with Accounts:

• Use src/hooks/useAccounts.ts
• Account components in src/components/accounts/
• AccountSelect component for booking forms

Booking Records (Completion Tracking)

Purpose: Record successful booking completions with payment details

Payment Methods: upi, net_banking, credit_card, debit_card, wallet

Implementation:

• Use src/hooks/useBookingRecords.ts
• BookingRecordForm for completion entry
• Link to original booking via booking ID

Common Patterns

Creating a New Booking

1. Define form schema with Zod
2. Use useForm with zodResolver
3. On submit, call Firestore addDoc
4. Invalidate React Query cache
5. Show toast notification

Editing an Existing Booking

1. Use query parameter routing (?id= for static export compatibility)
2. Pre-fill form with booking data
3. Convert Timestamps to strings for form fields
4. On submit, call Firestore updateDoc
5. Invalidate cache and navigate back

Updating Booking Status

1. Use StatusBadge component for display
2. StatusReasonDialog for status changes with reasons
3. Update Firestore document with new status
4. Invalidate relevant queries

Component Locations

Booking Components: src/components/bookings/

• BookingCard, BookingForm, BookingList, BookingsView
• StatusBadge, StatusReasonDialog, DateGroupHeading

Account Components: src/components/accounts/

• AccountSelect, AccountsTab, RefundsManager

Firestore Operations

Collection Names:

• bookings/ - Main booking records
• irctcAccounts/ - IRCTC credentials
• bookingRecords/ - Completion records
• handlers/ - Handler/agent names

Client SDK Methods:

• collection(), doc(), getDocs(), getDoc()
• addDoc(), updateDoc(), deleteDoc()
• onSnapshot() for real-time listeners

UI Patterns

Tabbed Interface: Separate 'Pending' and 'Completed' tabs with 'Pending' as default

Card-based Layout: Use Card components for organizing booking information

Date Grouping: Completed bookings grouped by date with DateGroupHeading

Infinite Scroll: Use intersection observer pattern for loading more bookings

Styling Guidelines

Follow the design system:

• Primary: #64B5F6 (calm blue)
• Background: #F0F4F7 (light gray)
• Accent: #4DB6AC (muted teal)
• Clean, sans-serif fonts (Open Sans)
• Simple, minimalist icons

Key Files to Reference

• src/hooks/useBookings.ts - Booking data management
• src/hooks/useAccounts.ts - Account management
• src/components/bookings/BookingForm.tsx - Complex form patterns
• src/types/booking.ts - Type definitions