CampusPool - Smart Cab Sharing Platform

🎯 Problem Statement

College students and working professionals often face challenges in commuting:

• High transportation costs for solo rides
• Difficulty finding co-travelers going the same route
• No reliable platform to coordinate cab sharing
• Safety concerns when sharing rides with strangers
• Complex cost splitting when multiple people share different portions of a journey

Traditional ride-hailing apps (Uber, Ola) don't offer features specifically designed for route-based cab pooling where users can share only the overlapping portion of their journeys.

💡 Solution Approach

CampusPool is an intelligent cab-sharing platform that uses advanced route-matching algorithms to connect travelers going in the same direction. Our unique approach includes:

Core Innovation: Subset/Superset Route Matching

Instead of requiring exact pickup/dropoff matches, our algorithm identifies:

• Subset matches: Your entire route is covered by someone else's trip
• Superset matches: Someone's trip is fully contained within your route
• Smart overlap detection: Finds trips sharing significant route segments

Key Differentiators

1. Fair Cost Splitting: Segment-based algorithm that divides costs proportionally based on actual distance traveled
2. Route Intelligence: Uses Google Maps polyline analysis to match routes going the same direction
3. Flexible Matching: 500m proximity threshold allows practical pickup/dropoff coordination
4. Real-time Notifications: Email alerts for trip requests, approvals, and payment reminders

🛠️ Tech Stack

Frontend

• Next.js 14.1.0 - React framework with App Router
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• Shadcn/UI - Accessible component library
• Lucide React - Icon system
• date-fns - Date formatting and manipulation

Backend

• Next.js API Routes - Serverless backend
• Prisma ORM - Type-safe database access
• SQLite - Lightweight database (development)
• Bcrypt - Password hashing
• Zod - Runtime type validation

External Services

• Google Maps Directions API - Route calculation and polyline generation
• Google Maps Geocoding API - Address to coordinates conversion
• Brevo (SendinBlue) - Transactional email delivery

Algorithm Libraries

• @googlemaps/polyline-codec - Route polyline encoding/decoding
• Haversine formula - Geographic distance calculations

✨ Key Features

1. Intelligent Route Matching

• Subset/superset route detection
• Directional overlap analysis
• Proximity-based matching (500m threshold)
• Time window filtering (±2 hours)

2. Trip Management

• Create Trips: Set origin, destination, departure time, and passenger capacity
• Real-time Updates: Track pending requests, confirmed co-travelers
• Trip Completion: Mark trips complete with automatic cost calculation

3. Smart Cost Splitting

• Segment-based fair splitting algorithm
• Proportional cost distribution based on distance traveled
• Automatic calculation considering overlapping route segments
• Payment tracking (Pending → Paid → Confirmed)

4. Request Management

• Send join requests for matching trips
• Approve/reject incoming requests
• Cancel requests before trip starts
• View contact information for confirmed trips

5. Email Notifications

• New join request alerts for trip hosts
• Approval confirmations for joiners
• Trip completion and payment notifications
• Cancellation alerts

6. User Interface

• Dark mode support
• Responsive design (mobile, tablet, desktop)
• Real-time form validation
• Interactive route visualization
• Google Maps integration

🚀 Instructions to Run the Code

Prerequisites

• Node.js 18+ installed
• npm or yarn package manager
• Google Maps API key (Get one here)
• Brevo API key (Get one here)

Step 1: Clone the Repository

git clone <repository-url>
cd hackiiit-2026-gathiyas

Step 2: Install Dependencies

npm install

Step 3: Set Up Environment Variables

Create a .env file in the root directory:

# Database
DATABASE_URL="file:./dev.db"

# Google Maps API
GOOGLE_MAPS_API_KEY="your_google_maps_api_key_here"

# Email Service (Brevo)
BREVO_API_KEY="your_brevo_api_key_here"
FROM_EMAIL="your-email@example.com"
FROM_NAME="CampusPool"

# Application (Optional)
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Step 4: Initialize Database

npx prisma generate
npx prisma db push

This creates the SQLite database and applies the schema.

Step 5: Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

Step 6: Create Your First Account

1. Click "Login" → "Don't have an account? Sign up"
2. Register with your name, email, phone, and password
3. Start creating or searching for trips!

Optional: Admin Panel

Access http://localhost:3000/admin to clear/reset the database.

📝 Previous Work & References

Open Source Projects Used

• Shadcn/UI: Used as base component library (shadcn/ui)
• Next.js Template: Initialized with create-next-app (Next.js)

Algorithm References

• Haversine Distance Formula: Standard geographic distance calculation (Wikipedia)
• Cross-Track Distance: For point-to-line distance calculations (Movable Type Scripts)
• Google Polyline Algorithm: For route encoding/decoding (Google Maps Documentation)

Inspiration

• Problem observed from personal experience coordinating cab sharing at IIIT Hyderabad
• Existing ride-sharing apps (Uber Pool, Ola Share) used as reference for UX patterns
• No codebase copied - built from scratch for HackIIIT 2026

🤖 AI Tools Disclosure

AI Tools Used

1. GitHub Copilot - Code completion and suggestions during development
2. Claude AI (Anthropic) - Algorithm design consultation and debugging assistance

Extent of AI Usage

• Algorithm Design: AI helped refine the subset/superset matching logic and polyline analysis
• Code Generation: ~30-40% of boilerplate code (UI components, API routes) generated with AI assistance
• Problem Solving: Used AI for debugging TypeScript errors and optimizing database queries
• Documentation: AI assisted in writing code comments and this README

Human Contribution

• Core Logic: Route matching algorithm designed and implemented by team
• Architecture: System design and database schema created by team
• Integration: Google Maps API and email service integration done manually
• Testing: All testing, debugging, and refinement done by team
• UI/UX: Design decisions and user flow created by team
• Business Logic: Cost splitting algorithm and trip management logic designed by team

Code Ownership

All code was reviewed, understood, and customized by our team. AI was used as a development accelerator, not a replacement for understanding. Every line of code in this repository has been:

• Reviewed for correctness
• Tested manually
• Understood completely
• Modified to fit our specific requirements

📚 Additional Documentation

Route Matching Algorithm

See ROUTE_MATCHING_ALGORITHM.md for detailed explanation of our subset/superset matching algorithm with examples.

Project Structure

app/
├── api/              # API routes (Next.js serverless functions)
│   ├── auth/        # Authentication endpoints (login, signup, logout)
│   ├── rides/       # Trip management (create, search, complete, delete)
│   ├── requests/    # Join request handling (approve, reject, cancel)
│   ├── payments/    # Payment tracking (update status)
│   └── admin/       # Admin utilities (clear database)
├── admin/           # Admin panel UI
└── page.tsx         # Main landing page

components/
├── ui/                      # Shadcn UI base components
├── AuthForm.tsx             # Login/signup form
├── CreateRideForm.tsx       # Trip creation form
├── UnifiedRideSearch.tsx    # Search interface with filters
├── MyRides.tsx              # Trip management dashboard
├── MyRequests.tsx           # Join request tracking
├── RideCard.tsx             # Trip display component
└── RouteVisualizer.tsx      # Google Maps integration

lib/
├── db.ts                # Prisma client singleton
├── auth.ts              # Authentication utilities
├── polyline-utils.ts    # Route matching algorithms
├── google-maps.ts       # Google Maps API integration
└── email.ts             # Email service (Brevo)

prisma/
└── schema.prisma        # Database schema (User, Ride, RideRequest)

Database Schema

model User {
  id        String   @id @default(cuid())
  name      String
  email     String   @unique
  password  String
  phone     String?
  createdAt DateTime @default(now())
}

model Ride {
  id              String        @id @default(cuid())
  driverId        String
  originAddress   String
  destAddress     String
  departureTime   DateTime
  maxPassengers   Int
  ghostMode       Boolean       @default(false)
  status          String        @default("OPEN")
  routePolyline   String
  totalCost       Float?
  rideRequests    RideRequest[]
  createdAt       DateTime      @default(now())
}

model RideRequest {
  id             String   @id @default(cuid())
  rideId         String
  passengerId    String
  status         String   @default("PENDING")
  amountOwed     Float?
  paymentStatus  String?
  createdAt      DateTime @default(now())
}

🔍 How It Works

1. Create a Trip

• Enter origin and destination addresses
• Set departure time and passenger capacity
• System calculates route using Google Maps
• Stores encoded polyline for matching

2. Search for Trips

• Enter your pickup and dropoff locations
• System finds trips with overlapping routes
• Displays match type (Subset/Superset) and overlap percentage
• Shows estimated pickup time and shared distance

3. Join a Trip

• Send join request to trip host
• Host receives email notification
• Host approves/rejects request
• Both parties receive email with contact info

4. Complete Trip

• Host marks trip complete after journey ends
• Enters total cost
• System calculates fair split based on segments
• Sends payment notifications to all co-travelers

5. Payment Tracking

• Joiners mark payment as "Paid"
• Host confirms receipt
• Status updates tracked in database

👥 Team

Team Name: Gathiyas

Members:

• Dev Kanani - Full Stack Development
• Shivansh Santoki - Full Stack Development
• Kavish Vora - Full Stack Development
• Jainam Modi - Full Stack Development

Institution: IIIT Hyderabad

Event: HackIIIT 2026

📄 License

This project is submitted for HackIIIT 2026 and is subject to the hackathon's terms and conditions.

🔒 Security Note

⚠️ Important:

• No .env files or API keys are committed to this repository
• All sensitive credentials must be configured locally
• Database file (dev.db) is gitignored
• Follow the setup instructions to configure your own API keys

🙏 Acknowledgments

• IIIT Hyderabad for hosting HackIIIT 2026
• Google Maps Platform for the Directions API
• Brevo for the email service
• Next.js and Vercel teams for the amazing framework
• Shadcn for the beautiful UI components

---

Built with ❤️ for HackIIIT 2026