TripCabShare - Neighborhood Airport Ride-Sharing

Share airport rides with your neighbors. Automatically detect trips from your Google Calendar, find neighbors traveling at similar times, and coordinate rides together.

Features

• Google Calendar Integration - Automatically detect airport trips from calendar events
• Anonymous Trip Display - Trips shown anonymously until you choose to connect
• Smart Matching - Match with neighbors based on airport, time, and preferences
• Community-Based - Create or join private neighborhood communities
• Real-time Notifications - WebSocket-powered instant updates

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router), TypeScript, Tailwind CSS, Radix UI
Backend	NestJS, TypeScript, Prisma ORM
Database	PostgreSQL
Cache/Queue	Redis + BullMQ
Real-time	WebSockets (Socket.io)
Auth	Google OAuth 2.0 + JWT

Project Structure

tripCabShareMode/
├── apps/
│   ├── api/           # NestJS backend
│   └── web/           # Next.js frontend
├── packages/
│   └── shared/        # Shared types & utilities
├── prisma/
│   └── schema.prisma  # Database schema
├── docker-compose.yml # PostgreSQL & Redis
├── turbo.json         # Turborepo config
└── package.json       # Root package

Prerequisites

• Node.js 20+
• pnpm 9+
• Docker & Docker Compose
• Google Cloud Console project with OAuth 2.0 credentials

Getting Started

1. Clone and Install

cd tripCabShareMode
pnpm install

2. Start Database Services

pnpm docker:up

3. Configure Environment

Copy the example environment files:

cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

Edit .env and apps/api/.env with your configuration:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/tripcabshare?schema=public"

# Redis
REDIS_URL="redis://localhost:6379"

# Google OAuth (from Google Cloud Console)
GOOGLE_CLIENT_ID="your-client-id"
GOOGLE_CLIENT_SECRET="your-client-secret"
GOOGLE_CALLBACK_URL="http://localhost:3001/auth/google/callback"

# JWT Secrets (generate secure random strings)
JWT_SECRET="your-jwt-secret"
JWT_REFRESH_SECRET="your-refresh-secret"

4. Setup Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the Google Calendar API
4. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
5. Configure OAuth consent screen
6. Add authorized redirect URI: http://localhost:3001/auth/google/callback
7. Copy Client ID and Client Secret to your .env files

Required OAuth scopes:

• email
• profile
• https://www.googleapis.com/auth/calendar.readonly

5. Initialize Database

cd apps/api
pnpm db:generate  # Generate Prisma client
pnpm db:push      # Push schema to database

6. Start Development Servers

From the root directory:

pnpm dev

This starts:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• Swagger Docs: http://localhost:3001/api/docs

API Endpoints

Module	Endpoint	Description
Auth	GET /auth/google	Initiate Google OAuth
Auth	GET /auth/google/callback	OAuth callback
Auth	POST /auth/refresh	Refresh access token
Calendar	POST /calendar/connect	Enable calendar sync
Calendar	POST /calendar/sync	Manual sync trigger
Communities	GET /communities	List user's communities
Communities	POST /communities	Create community
Communities	POST /communities/join/:code	Join with invite code
Trips	GET /trips	List user's trips
Trips	GET /trips/community/:id	Community trip feed
Matches	GET /matches	List user's matches
Matches	POST /matches/:id/accept	Accept match
Matches	GET /matches/:id/contact	Get contact info

Development

Running Tests

pnpm test

Building for Production

pnpm build

Database Migrations

cd apps/api
pnpm db:migrate  # Create migration

Architecture

Matching Algorithm

The matching engine runs every 15 minutes and scores potential matches based on:

Factor	Weight
Time Proximity	40%
Preference Match	30%
Historical Success	20%
Cost Efficiency	10%

Matches with a score >= 50 are proposed to users.

Real-time Updates

WebSocket events are sent for:

• New match proposals
• Match status changes
• Trip detection from calendar
• Community updates

Privacy

• Trips are displayed anonymously in community feeds
• Contact info (email, phone) only revealed after mutual match acceptance
• Users control which communities can see their travel plans

Deployment

Frontend (Vercel)

vercel --prod

Backend (Railway/Render)

1. Connect GitHub repository
2. Set environment variables
3. Deploy

Database

Use a managed PostgreSQL service:

• Supabase
• Neon
• Railway PostgreSQL

License

MIT