🚗 Transport Pool Backend

A modern ride-sharing/carpooling backend system built with Hono.js and deployed on Cloudflare Workers. Designed specifically for Thapar University students to share transportation.

🌟 Features

• Google OAuth Authentication - Secure login restricted to @thapar.edu domain
• JWT-based Authorization - Access tokens (1h) and refresh tokens (7d)
• Pool Management - Create, join, and manage transport pools
• Female-only Pools - Gender-restricted pools for safety
• Advanced Filtering - Search by location, time, transport mode
• Real-time Capacity - Automatic capacity tracking
• Type-safe - Full TypeScript implementation with Drizzle ORM

🛠️ Tech Stack

• Runtime: Cloudflare Workers
• Framework: Hono.js (Ultra-fast web framework)
• Database: Cloudflare D1 (SQLite)
• ORM: Drizzle ORM
• Authentication: Google OAuth 2.0 + JWT
• Language: TypeScript

📋 Prerequisites

• Node.js 18+ installed
• Cloudflare account (free tier works)
• Google Cloud Console account (for OAuth credentials)
• Wrangler CLI installed globally

npm install -g wrangler

🚀 Quick Start

1. Clone and Install

git clone <repository-url>
cd transport-pool-backend
npm install

2. Configure Environment

# Login to Cloudflare
wrangler login

# Copy environment template
cp .dev.vars.example .dev.vars

Edit .dev.vars:

JWT_SECRET=your-super-secret-jwt-key-min-32-chars
JWT_REFRESH_SECRET=your-refresh-token-secret
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret
FRONTEND_URL=http://localhost:3000
ALLOWED_DOMAIN=thapar.edu

3. Setup Database

# Create D1 database
wrangler d1 create transport-pool-db

# Update wrangler.toml with database_id from above command

# Run migrations
npm run db:migrate

4. Run Development Server

npm run dev

Server runs at: http://localhost:8787

📦 Available Scripts

npm run dev          # Start development server
npm run deploy       # Deploy to Cloudflare Workers
npm run db:generate  # Generate database migrations
npm run db:migrate   # Apply migrations to D1
npm run db:studio    # Open Drizzle Studio (local)
npm run test         # Run tests
npm run lint         # Lint code
npm run typecheck    # Type checking

🔑 Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Google+ API
4. Create OAuth 2.0 credentials:
   • Application type: Web application
   • Authorized redirect URIs:
     • http://localhost:8787/auth/google/callback (dev)
     • https://your-worker.workers.dev/auth/google/callback (prod)
5. Copy Client ID and Client Secret to .dev.vars

📡 API Endpoints

Authentication

• POST /auth/google - Initiate Google OAuth
• GET /auth/google/callback - OAuth callback
• POST /auth/refresh - Refresh access token
• POST /auth/logout - Logout user

User Management

• GET /user/profile - Get current user profile
• PUT /user/profile - Update user profile
• POST /user/phone - Update phone number
• POST /user/gender - Update gender

Pool Management

• GET /pools - List all pools (with filters)
• POST /pools - Create new pool
• GET /pools/:id - Get pool details
• PUT /pools/:id - Update pool (creator only)
• DELETE /pools/:id - Delete pool (creator only)
• POST /pools/:id/join - Join a pool
• POST /pools/:id/leave - Leave a pool

Query Parameters (for GET /pools)

• start_point - Filter by starting location
• end_point - Filter by destination
• transport_mode - Filter by transport type
• is_female_only - Filter female-only pools
• departure_date - Filter by date (YYYY-MM-DD)
• search - Search in locations
• ordering - Sort by field (departure_time, -created_at)

🗄️ Database Schema

Users Table

• id - UUID primary key
• email - Unique, @thapar.edu only
• full_name - User's full name
• phone_number - Optional contact
• gender - male/female/other
• google_authenticated - Boolean flag
• created_at / updated_at - Timestamps

Pools Table

• id - UUID primary key
• start_point - Starting location
• end_point - Destination
• departure_time - DateTime
• transport_mode - train/bus/car/bike/other
• total_persons - Maximum capacity
• current_persons - Current occupancy
• is_female_only - Boolean flag
• created_by_id - Foreign key to users
• created_at / updated_at - Timestamps

Pool Members Table

• id - UUID primary key
• pool_id - Foreign key to pools
• user_id - Foreign key to users
• is_creator - Boolean flag
• joined_at - Timestamp

🔒 Security Features

• Domain-restricted Google OAuth (@thapar.edu)
• JWT tokens with expiration
• Refresh token rotation
• CORS protection
• Rate limiting (via Cloudflare)
• SQL injection prevention (Drizzle ORM)
• XSS protection (input sanitization)

🌍 Deployment

Production Deployment

# Deploy to Cloudflare Workers
npm run deploy

# Set production secrets
wrangler secret put JWT_SECRET
wrangler secret put JWT_REFRESH_SECRET
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET

Environment Variables (Production)

Set via Cloudflare Dashboard or Wrangler:

• JWT_SECRET - Production JWT secret
• JWT_REFRESH_SECRET - Refresh token secret
• GOOGLE_CLIENT_ID - Google OAuth client ID
• GOOGLE_CLIENT_SECRET - Google OAuth secret
• FRONTEND_URL - Your frontend URL
• ALLOWED_DOMAIN - thapar.edu

📊 Monitoring

Monitor your worker at:

• Cloudflare Dashboard > Workers > Analytics
• Real-time logs: wrangler tail
• Metrics: Requests, errors, CPU time

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

📝 API Response Format

Success Response

{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

MIT License - see LICENSE file for details

👥 Authors

• Your Name - Initial work

🙏 Acknowledgments

• Hono.js team for the amazing framework
• Cloudflare for Workers platform
• Drizzle team for the ORM

📞 Support

For issues and questions:

• Open an issue on GitHub
• Email: support@example.com

🗺️ Roadmap

• Email notifications
• Push notifications
• Rating system
• Chat functionality
• Route optimization
• Payment integration
• Admin dashboard

---

Made with ❤️ for Thapar University students