JNW Lanka Tours - Booking System

A modern web application for Sri Lankan tour and vehicle booking services built with Next.js 15, TypeScript, and Tailwind CSS.

🚀 Features

✅ Core Functionality

• Vehicle Booking System with real-time pricing calculation
• Tour Package Management with detailed information
• Contact Form with dual email notifications (customer + business)
• Email Integration via SendGrid for confirmations
• Google Analytics tracking with comprehensive event monitoring
• Responsive Design optimized for all devices

🎯 Key Integrations

• Supabase - Database (PostgreSQL) for tours, vehicles, and locations
• SendGrid - Email delivery service
• Google Analytics GA4 - Analytics and event tracking
• reCAPTCHA - Form spam protection
• Vercel Analytics - Performance monitoring

📋 Prerequisites

• Node.js 18+
• npm or yarn
• Supabase account
• SendGrid account
• Google Analytics property
• reCAPTCHA site keys

🛠️ Setup Instructions

1. Clone & Install

git clone <repository-url>
cd jnw
npm install

2. Environment Variables

Create .env.local with the following variables:

# Database
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Email Service
SENDGRID_API_KEY=your_sendgrid_api_key

# Analytics
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

# Security
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_recaptcha_site_key
RECAPTCHA_SECRET_KEY=your_recaptcha_secret_key

# Admin Authentication
PASSWORD=your_admin_password
ADMIN_API_KEY=your_admin_api_key

3. Development Setup Options

Option A: Docker Development (Recommended)

Full containerized development environment with PostgreSQL database:

# Start all services (Next.js + PostgreSQL + pgAdmin)
npm run docker:dev

# Or using docker-compose directly
docker-compose up -d

# Stop services
docker-compose down

Docker Services:

• Next.js Dev Server: http://localhost:3000
• PostgreSQL Database: localhost:5432
• pgAdmin: http://localhost:8080 (admin@jnw.com / admin)

Docker Environment:

• Database automatically initialized with schema and sample data
• No local database setup required
• Isolated development environment

Option B: Local Development

For local development without Docker:

# Ensure PostgreSQL is running locally
# Update .env.local with local database URL:
# DATABASE_URL=postgresql://postgres:postgres@localhost:5432/jnw_tours

npm run dev

4. Database Setup

With Docker

Database is automatically set up with:

• Schema initialization from schema.sql
• Sample data import from CSV files
• Health checks and automatic retries

Without Docker (Supabase)

Ensure your Supabase database has the following tables:

• tours - Tour packages with details
• vehicles - Available vehicles with pricing
• locations - Pickup/dropoff locations

5. SendGrid Configuration

1. Create SendGrid account and get API key
2. Verify sender email addresses
3. Configure domain authentication (for production)

6. Google Analytics Setup

1. Create GA4 property
2. Add measurement ID to environment variables
3. Configure data streams for your domains

7. Run Development Server

# Docker (recommended)
npm run docker:dev

# Local
npm run dev

Open http://localhost:3000

📁 Project Structure

src/
├── app/                    # Next.js 15 app router
│   ├── api/               # API routes
│   │   ├── admin/         # Admin-only endpoints (tours, vehicles, locations)
│   │   ├── auth/          # Authentication endpoints (password)
│   │   ├── bookings/      # Booking submissions
│   │   ├── contact/       # Contact form handler
│   │   ├── locations/     # Location data
│   │   └── tours/         # Tour data
│   ├── admin/             # Admin panel pages (password protected)
│   ├── booking/           # Booking flow pages
│   ├── contact/           # Contact page
│   ├── tours/             # Tour pages
│   └── analytics-test/    # GA debugging tools
├── components/            # React components
│   ├── admin/             # Admin panel components
│   ├── analytics/         # Google Analytics integration
│   ├── booking/           # Booking-related components
│   ├── contact/           # Contact form
│   ├── home/              # Homepage components
│   ├── layout/            # Layout components (Header, Footer)
│   ├── shared/            # Shared components (Hero, PasswordGate, ErrorBoundary)
│   ├── tours/             # Tour display components
│   ├── ui/                # Reusable UI components
│   │   ├── Button.tsx     # Button component with variants
│   │   ├── Input.tsx      # Form input component
│   │   ├── Select.tsx     # Dropdown select component
│   │   ├── Textarea.tsx   # Textarea component
│   │   ├── ErrorMessage.tsx # Error message display
│   │   ├── SuccessMessage.tsx # Success message display
│   │   └── NavLink.tsx    # Navigation link component
│   └── vehicles/          # Vehicle display components
├── constants/             # Static data and configurations
├── hooks/                 # Custom React hooks
│   ├── useAdminCrud.ts   # Admin CRUD operations hook
│   └── useRecaptcha.ts   # reCAPTCHA integration hook
├── utils/                 # Utility functions
│   ├── api.ts            # Centralized fetch wrapper
│   ├── auth.ts           # Authentication utilities
│   ├── config.ts         # Configuration management
│   ├── date.ts           # Date parsing and calculation
│   ├── db.ts             # Database helpers (Supabase)
│   ├── email.ts          # Email templates and sending
│   ├── format.ts         # Data formatting utilities
│   ├── image.ts          # Image source handling
│   ├── logger.ts         # Logging utilities
│   ├── passwordAuth.ts   # Password authentication utilities
│   ├── recaptcha.ts      # reCAPTCHA validation
│   └── validation.ts     # Form validation
└── styles/               # Global styles

🎨 Key Components

Vehicle Booking Flow

1. VehicleSelection - Choose vehicle and view pricing
2. BookingPageClient - Manage booking state
3. FullBookingForm - Complete booking details with reCAPTCHA
4. Email Confirmation - Automated SendGrid emails

Admin Panel

• PasswordGate - Password authentication wrapper
• useAdminCrud Hook - Reusable CRUD operations for admin pages
• Admin Forms - Tour, Vehicle, and Location management
• Cookie-based Authentication - Secure admin access

Reusable UI Components

• Button - Variants: primary, secondary, danger, outline, ghost
• Input - Form input with label and error support
• Select - Dropdown select component
• Textarea - Multi-line text input
• ErrorMessage/SuccessMessage - User feedback components
• NavLink - Consistent navigation links

Contact System

• Dual Email System: Customer confirmation + Business notification
• reCAPTCHA Protection: Spam prevention via useRecaptcha hook
• Tour Integration: Pre-select tours from links

Analytics Tracking

• Page views and user interactions
• Booking funnel events
• Contact form submissions
• Vehicle interest tracking

Font Optimization

• Next.js Font Optimization: Using next/font/google
• Inter: Primary sans-serif font
• Poppins: Display font for headings
• Automatic font subsetting and optimization

🔧 Development Features

Email Testing

• Customer confirmation emails
• Business notification emails
• SendGrid integration with detailed logging

Analytics Debugging

Visit /analytics-test for comprehensive GA debugging:

• Event testing tools
• Real-time data verification
• DataLayer inspection
• Console logging

Environment Support

• Development mode with enhanced logging
• Production optimizations
• Environment-specific configurations

📊 Monitoring & Analytics

Google Analytics Events

• booking_started - User begins booking process
• booking_completed - Successful booking submission
• contact_form_submitted - Contact form submissions
• vehicle_viewed - Vehicle detail views

Email Tracking

• SendGrid message IDs for delivery tracking
• Success/failure logging
• Customer and business email confirmations

🚀 Deployment

Vercel (Recommended)

npm run build
vercel deploy

Environment Variables for Production

Ensure all environment variables are configured in your deployment platform.

Domain Configuration

• Update Google Analytics allowed domains
• Configure SendGrid domain authentication
• Update reCAPTCHA allowed domains

🐛 Troubleshooting

Email Issues

• Verify SendGrid API key and sender email
• Check spam folders for test emails
• Review SendGrid activity dashboard

Analytics Issues

• Use /analytics-test debug page
• Check browser console for errors
• Verify GA measurement ID
• Ensure domain is allowed in GA property

Database Issues

• Verify Supabase credentials
• Check RLS policies if enabled
• Review database schema

🤝 Contributing

1. Follow TypeScript best practices
2. Use modular component architecture
3. Maintain comprehensive error handling
4. Add tests for new features
5. Update documentation for changes

📝 API Reference

POST /api/bookings

Submit vehicle booking with customer details and send confirmation emails.

POST /api/contact

Process contact form submissions with dual email notifications.

GET /api/tours

Retrieve available tour packages.

GET /api/locations

Retrieve pickup/dropoff locations.

🔒 Security & Authentication

Admin Authentication

• Password-based authentication via /api/auth/password
• Cookie-based session management (auth_token cookie, 24-hour expiration)
• API key fallback for programmatic access (x-api-key header)
• PasswordGate component protects all admin pages
• Admin API routes accept either password cookie OR API key header

Form Security

• reCAPTCHA v3 protection on contact and booking forms
• Input validation and sanitization on all forms
• Server-side validation for all API endpoints

General Security

• Environment variable security
• HTTPS enforcement in production
• Rate limiting (recommended for production)

📜 License

[Add your license information here]

---

Built with ❤️ for JNW Lanka Tours