Product Requirements Document (PRD): CarpoolConnect

1. Executive Summary

CarpoolConnect is a specialized logistics add-on for the Meetup ecosystem designed to solve the "last-mile" accessibility gap for community events. By leveraging real-time geospatial matching and a community-driven trust system, the app enables event attendees to discover, coordinate, and share rides. Unlike general ride-sharing apps, CarpoolConnect focuses on event-specific clusters, providing organizers with tools to reduce parking congestion and carbon footprints while increasing attendance rates for members without personal transportation.

2. Problem Statement

Meetup organizers frequently face lower attendance rates due to limited venue parking and the lack of reliable transportation for some members. Currently, ride coordination happens via fragmented comment threads, leading to safety concerns (sharing addresses publicly) and logistical failures (missed connections). There is no automated, secure way to match attendees based on their route proximity and trust levels within the community.

3. Goals & Success Metrics

Goal 1: Increase event accessibility for non-drivers.
- Metric: % increase in RSVP-to-attendance conversion for carpool-enabled events.
Goal 2: Reduce the environmental impact of community gatherings.
- Metric: Total CO2 kilograms saved (calculated via distance traveled vs. car occupancy).
Goal 3: Foster community trust.
- Metric: Average "Trust Score" of active carpoolers and % of successful (unflagged) rides.

4. User Personas

A. The Organizer (Sarah, 34)

Need: Wants her "Hiking Enthusiasts" group to thrive without worrying about the 10-car limit at the trailhead.
Pain Point: Spent too much time manually answering "Can anyone give me a lift?" in the comments.

B. The Proactive Driver (Mark, 42)

Need: Already driving to the event and wants to help the community/split gas costs.
Pain Point: Doesn't want to go 20 minutes out of his way or pick up "strangers" without some verification.

C. The Carless Attendee (Elena, 23)

Need: Needs a ride to an evening board game night across town.
Pain Point: Feels awkward asking for rides and is concerned about safety when meeting people for the first time.

5. User Stories

As an Organizer, I want to sync my Meetup events so that I can enable carpooling options with one click.
As a Driver, I want the system to suggest riders who are already on my route so that I minimize my detour time.
As a Rider, I want my exact pickup location to remain hidden until I approve a match so that my privacy is protected.
As an Attendee, I want to see a carbon savings dashboard so that I can feel good about my environmental impact.

6. Functional Requirements

6.1 Event Synchronization

Integration: Connection to Meetup GraphQL API (2026 standard) to fetch group events, dates, and locations.
Manual Override: Organizers can toggle carpooling "On" or "Off" per event.

6.2 Geospatial Matching Engine

Role Selection: Users must register as a "Driver" (with seat capacity) or "Rider."
Two-Step Matching logic:
1. Gross Match: Identify drivers and riders within a 5-mile radius of the same event.
2. Fine-Grained Detour Analysis: Calculate if a rider’s pickup/drop-off adds <15 minutes to the driver's original route.

6.3 Secure Communication

In-App Chat: Real-time group messaging for matched carpools using Socket.io.
Privacy Guard: Precise addresses are obfuscated on the map until a "Confirmed" state is reached by both parties.

6.4 Trust & Safety System

Trust Score: A Bayesian-weighted average of community ratings, identity verification, and event attendance history.
Reciprocal Rating: Drivers and riders rate each other post-event; ratings are only revealed once both have submitted.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

Frontend: Next.js v16.1.3 utilizing Partial Pre-Rendering (PPR) for instant map shell loading and React 19 View Transitions for smooth UI state changes.
Backend: NestJS v11.1.12 using the Command Query Responsibility Segregation (CQRS) pattern for handling ride events.
Database: PostgreSQL 18 with PostGIS 3.5+ for asynchronous spatial I/O and SP-GIST indexing for proximity searches.
Real-time: Socket.io (with Redis adapter for horizontal scaling).
Background Jobs: BullMQ for managing notification queues and detour calculations.

7.2 Integrations

Auth: Meetup OAuth 2.0 with PKCE.
Maps/Routing: Google Routes API for eco-friendly routing and TollGuru for pro-rata gas money split estimations.
Notifications: Twilio for SMS alerts; SendGrid for transactional emails.

8. Data Model

Entities & Relationships

User: userId, meetupId, trustScore, isVerified, vehicleDetails.
Event: meetupEventId, groupId, locationGeom, startTime.
CarpoolGroup: groupId, driverId, eventLink, routePolyline, status (Open/Full/Completed).
RideRequest: requestId, riderId, pickupGeom, dropoffGeom, matchStatus.
Review: reviewId, rideId, raterId, ratee_id, stars, safetyFlags.

9. API Specification (Sample Endpoints)

`GET /api/v1/events/sync`

Description: Imports upcoming events from Meetup GraphQL API.
Response: 200 OK with array of Event objects.

`POST /api/v1/carpools/match`

Request: { userId: string, eventId: string, role: 'driver' | 'rider', location: [lat, lng] }
Logic: Triggers the PostGIS ST_DWithin and ST_LineLocatePoint matching algorithm.
Response: List of potential matches with "Trust Scores" and "Detour Time."

10. UI/UX Requirements

Map-Centric Interface: Uses a client-side Mapbox/Leaflet boundary to prevent hydration errors in Next.js 16.
Snappy Transitions: Use React 19 <Activity /> components to keep map state "alive" while users switch between the list of carpools and their personal profile.
Privacy UI: Use "Circular Geofences" to show approximate locations of riders to drivers before a match is accepted.

11. Non-Functional Requirements

Performance: Proximity searches must return results in <500ms using SP-GIST spatial indexing.
Security: PII (Precise addresses) must be encrypted at rest using AES-256.
Scalability: The notification worker must handle up to 10k concurrent SMS alerts via BullMQ rate-limiting.

12. Out of Scope

Payment Processing: The app provides estimates for gas splits but does not handle actual monetary transactions (to avoid being classified as a taxi service).
Inter-city Travel: Initial release is limited to intracity carpooling (radius < 50 miles).

13. Risks & Mitigations

Risk: Safety incidents during carpools.
- Mitigation: Mandatory Meetup OAuth verification and a tiered "Trust Score" system where low-rated users are automatically banned.
Risk: High API costs for Google Maps.
- Mitigation: Implementation of TomTom API as a fallback for the free daily tier and aggressive caching of route polylines.

14. Implementation Tasks

Phase 1: Project Setup

[ ] Initialize Next.js 16.1.3 project with Tailwind CSS.
[ ] Set up NestJS 11.1.12 with PostgreSQL/PostGIS 3.5.
[ ] Configure Meetup OAuth 2.0 Strategy with Passport.js.

Phase 2: Core Event & Map Logic

[ ] Create PostGIS schema for User and Event locations.
[ ] Implement Meetup GraphQL sync worker.
[ ] Build the map-based event discovery UI using next/dynamic.

Phase 3: Matching Algorithm & Messaging

[ ] Develop the "Two-Step Match" SQL procedure using ST_DWithin and ST_LineLocatePoint.
[ ] Integrate BullMQ for background detour calculations.
[ ] Implement real-time group chat using Socket.io and NestJS Gateways.

Phase 4: Trust, Safety & Carbon

[ ] Build the Bayesian Average rating system logic.
[ ] Integrate TollGuru API for gas and carbon estimation.
[ ] Implement address obfuscation logic (coarse-to-fine disclosure).

Phase 5: Notifications & Launch

[ ] Set up Twilio SMS triggers for match confirmations.
[ ] Finalize the "Carbon Savings" dashboard UI.
[ ] Deploy to Vercel (Frontend) and AWS RDS (Database).