LinkCab - Social Cab Sharing Assistant

A modern, social-first cab-sharing platform that connects verified commuters to split ride fares and reduce daily commute costs.

🚀 Features

• OTP-based Authentication - Secure phone number verification
• Real-time Ride Matching - Find and connect with fellow commuters
• Smart Route Optimization - AI-powered matching for optimal routes
• Google API Integration - Location search, geocoding, and route planning
• Intelligent Profile Classification - User type detection and trust scoring
• Personalized Recommendations - AI-powered ride matching based on preferences
• Secure Payment Integration - Split fares safely with integrated payments
• User Verification System - Build trust with verified profiles
• Real-time Notifications - Stay updated with ride requests and updates
• Modern UI/UX - Beautiful, responsive design with Tailwind CSS

🛠️ Tech Stack

Frontend

• React 18 - Modern React with hooks and functional components
• React Router - Client-side routing
• Tailwind CSS - Utility-first CSS framework
• Lucide React - Beautiful icons
• React Query - Server state management
• Axios - HTTP client
• React Hot Toast - Toast notifications
• Framer Motion - Animations

Backend

• Node.js - JavaScript runtime
• Express.js - Web framework
• MongoDB - NoSQL database
• Mongoose - MongoDB ODM
• JWT - Authentication
• Socket.IO - Real-time communication
• Google APIs - Places, Geocoding, Directions
• Twilio - SMS/OTP service
• Razorpay - Payment gateway
• Redis - Caching (optional)

📦 Installation

Prerequisites

• Node.js (v16 or higher)
• MongoDB (local or cloud)
• npm or yarn
• Google Cloud Console account (for API integration)

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd linkcab

2. Install dependencies

   npm run install-all

3. Environment Setup

   # Copy environment file
   cd server
   copy env.example .env

4. Configure Environment Variables Edit server/.env and update the following:

   MONGODB_URI=mongodb://localhost:27017/linkcab
   JWT_SECRET=your-super-secret-jwt-key
   TWILIO_ACCOUNT_SID=your_twilio_account_sid
   TWILIO_AUTH_TOKEN=your_twilio_auth_token
   TWILIO_PHONE_NUMBER=your_twilio_phone_number
   GOOGLE_API_KEY=your_google_api_key_here

5. Google API Setup (Optional but recommended)

   • Go to Google Cloud Console
   • Enable: Places API, Geocoding API, Directions API
   • Create API credentials and add to .env

6. Start Development Servers

   npm run dev

   This will start:

   • Frontend: http://localhost:3000
   • Backend: http://localhost:5000

🚀 Available Scripts

• npm run dev - Start both frontend and backend in development mode
• npm run server - Start only the backend server
• npm run client - Start only the frontend development server
• npm run build - Build the frontend for production
• npm run install-all - Install dependencies for all packages

📱 Usage

1. Visit the application at http://localhost:3000
2. Sign up/Login using your phone number and OTP
3. Complete your profile with personal information
4. Browse available rides or create your own ride announcement
5. Use location search to find nearby places and routes
6. Get personalized recommendations based on your profile and preferences
7. Connect with commuters and start sharing rides!

🔧 Configuration

Frontend Configuration

The frontend is configured to proxy API requests to the backend at http://localhost:5000/api. You can modify this in client/package.json:

{
  "proxy": "http://localhost:5000"
}

Backend Configuration

The backend uses environment variables for configuration. See server/env.example for all available options.

Google API Configuration

For full functionality, configure Google APIs:

1. Enable required APIs in Google Cloud Console
2. Create API credentials
3. Add API key to environment variables
4. Set up API restrictions for security

🏗️ Project Structure

linkcab/
├── client/                 # React frontend
│   ├── public/            # Static files
│   ├── src/
│   │   ├── components/    # Reusable components
│   │   │   ├── LocationSearch.js      # Google Places integration
│   │   │   └── RideRecommendations.js # AI recommendations
│   │   ├── pages/         # Page components
│   │   ├── context/       # React context
│   │   ├── hooks/         # Custom hooks
│   │   └── utils/         # Utility functions
│   └── package.json
├── server/                # Node.js backend
│   ├── models/           # MongoDB models
│   │   └── User.js       # Enhanced with profile classification
│   ├── routes/           # API routes
│   │   └── google.js     # Google API endpoints
│   ├── middleware/       # Express middleware
│   ├── services/         # Business logic
│   │   ├── googleApiService.js      # Google API integration
│   │   └── recommendationService.js # AI recommendations
│   └── package.json
├── GOOGLE_API_INTEGRATION.md  # Detailed API documentation
└── package.json          # Root package.json

🧠 AI & Intelligence Features

Profile Classification

• User Type Detection: Automatically classify users as business travelers, students, regular commuters, etc.
• Trust Scoring: Calculate user reliability based on ratings, verification, and activity
• Compatibility Matching: Match users based on preferences and behavioral patterns

Recommendation System

• Personalized Matching: AI-powered ride recommendations
• Multi-factor Scoring: Distance, time, profile level, and preferences
• Smart Filtering: Location-based and preference-based filtering

Google API Integration

• Location Search: Find places, landmarks, and addresses
• Geocoding: Convert addresses to coordinates and vice versa
• Route Planning: Get directions and route information
• Nearby Places: Discover places around a location

🔒 Security Features

• JWT-based authentication
• Phone number verification via OTP
• Rate limiting on API endpoints
• Input validation and sanitization
• CORS configuration
• Helmet.js security headers
• Google API key protection

🚧 Development Status

This project is currently in development. The following features are implemented:

✅ Completed:

• User authentication (OTP-based)
• Basic UI components and pages
• Responsive design
• Navigation and routing
• User profile management
• Google API integration
• Profile classification system
• AI-powered recommendations
• Location search and geocoding

🔄 In Progress:

• Ride announcement creation
• Ride matching and discovery
• Real-time notifications
• Payment integration

📋 Planned:

• Advanced search and filtering
• Ride history and analytics
• Social features and reviews
• Mobile app development
• Machine learning enhancements

📚 Documentation

• Google API Integration Guide - Complete guide for Google API setup and usage
• Feedback System Documentation - AI-powered feedback and rating system
• Setup Guide - Detailed setup instructions

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Contact the development team

🙏 Acknowledgments

• Icons by Lucide
• UI components inspired by modern design systems
• Google APIs for location services
• Built with love for the commuting community

---

LinkCab - Making commuting social, affordable, and sustainable! 🚗💚