Project Info
This project did not submit a demo video on Devpost.
Inspiration
We noticed that whenever there were off-campus club activities, there was always a large number of people in need of rides to get to the venue. Event organizers would do their best to assign drivers for each rider through messy group chats, but the process was often manual, time-consuming, and inefficient. Many times, drivers had to take longer detours to pick up riders who other nearby drivers could have picked up. This led to unnecessary delays and confusion, which often resulted in frustration for both drivers and passengers. With VroomMates, we wanted to centralize and automate the planning of carpools by creating a solution that optimizes rider-driver assignments. The goal was to make the process of organizing rides easier and more efficient for both event organizers and participants. The idea of using technology to solve this common issue inspired us to create a tool that not only streamlines the ride-matching process but also minimizes detours and travel time, making it a win-win for everyone involved.
What it does
VroomMates is a carpool management system that centralizes the process of organizing carpools for events. It allows users to register as drivers or riders, input their locations and destinations, and automatically match riders with drivers based on optimal routes. VroomMates uses A* for pathfinding and linear distance using the Haversine Formula to cluster the drivers. This reduces unnecessary detours and streamlines transportation logistics.
How we built it
VroomMates was built using a full-stack approach. The front end was developed with React, leveraging the Google Maps API for location input, tracking, and map displays. The back end was powered by Flask, where Python handled the clustering algorithms to generate optimized driver routes. These routes were stored in Google Datastore, allowing users to save and resume their sessions across devices. We implemented continuous deployment with GitHub Actions and hosted the app on Vercel to streamline development and updates.
Challenges we ran into
One of the biggest challenges we encountered was creating the Post and Get functions for Flask. Since we modularized the entire project and everybody worked on different parts simultaneously, we saved the Flask implementation for the very last. Even though we were sure that all the parts worked independently, connecting the backend operations to display on the front end proved to be messier than we anticipated.
Accomplishments we're proud of
We are proud that our program works.
What we learned
The hackathon prize is the friends we made along the way.
What's next
Add functionality for live contribution between drivers and riders for the same map. Support the ability to add a desired arrival time and VroomMates will give routes that takes current traffic conditions into consideration. Oh, and IPO as a trillion-dollar company.
VroomMates
Carpool webapp — a React + Flask application that groups passengers with drivers heading to a shared destination and suggests an optimized route for each driver.
The repo contains both the frontend (React, in src/ and public/) and the
backend (Flask, in app.py and backend/) in a single project.
Prerequisites
You will need the following installed locally:
- Node.js 18 or newer — https://nodejs.org/
- npm (ships with Node.js) — verify with
npm --version - Python 3.10 or newer — https://www.python.org/downloads/
- pip (ships with Python) — verify with
pip --version
The repo's existing
requirements.txtwas generated against Python 3.12, so 3.10+ is recommended. On macOS and most Linux distros,pythonandpipmay be calledpython3andpip3— substitute as needed.
1. Clone and enter the repo
git clone https://github.com/jonnypan2325/VroomMates.git
cd VroomMates
2. Create your .env file
Copy the template and fill in your own keys:
cp .env.example .env
Then open .env and replace the placeholder values. See
Getting the Google credentials below.
3. Install Python dependencies
It is strongly recommended to use a virtual environment so the backend's packages don't pollute your system Python:
python -m venv .venv
# macOS / Linux:
source .venv/bin/activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
The .venv/ directory is already listed in .gitignore.
4. Install Node dependencies
npm install
This installs both the React app and the dev tooling (including
concurrently, which the dev
script below uses to run the frontend and backend together).
5. Run the app
You have three options.
Option A — run both servers together (recommended)
npm run dev
This uses concurrently to start the Flask backend (python app.py) and the
React dev server (react-scripts start) in a single terminal. Output from each
process is prefixed with backend or frontend.
Option B — run each server in its own terminal
In one terminal, start the backend:
python app.py
In a second terminal, start the frontend:
npm start
Default ports
| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| Backend | http://localhost:5000 |
The frontend talks to the backend over HTTP, so both servers must be running at the same time for the app to work end-to-end. If you only start one, the UI will load but route optimization requests will fail.
Getting the Google credentials
Google OAuth Client ID (REACT_APP_GOOGLE_CLIENT_ID)
- Go to the Google Cloud Console — Credentials page.
- Create (or select) a project.
- Click Create Credentials → OAuth client ID.
- If prompted, configure the OAuth consent screen first (External, just fill in the required fields).
- Choose Web application as the application type.
- Under Authorized JavaScript origins, add
http://localhost:3000. - Under Authorized redirect URIs, also add
http://localhost:3000. - Copy the generated Client ID and paste it into
.envasREACT_APP_GOOGLE_CLIENT_ID.
Google Maps API key (REACT_APP_GOOGLE_MAPS_API_KEY)
- In the same Credentials page, click Create Credentials → API key.
- From the API Library, enable
these APIs for your project:
- Maps JavaScript API
- Places API
- Copy the API key and paste it into
.envasREACT_APP_GOOGLE_MAPS_API_KEY. - The frontend's Maps script tag in
public/index.htmlreads the key via Create React App's%REACT_APP_GOOGLE_MAPS_API_KEY%HTML substitution, which is resolved at build time — you don't need to editindex.htmlyourself. (If you change.env, restartnpm startfor the new value to be picked up.) - It is highly recommended to add HTTP referrer restrictions to the key in the Google Cloud Console so it can only be used from your domains.
Flask backend URL (REACT_APP_FLASK_API_URL)
The React frontend reads REACT_APP_FLASK_API_URL to know where the Flask
backend is running. For local development, leave the value in .env.example
(http://127.0.0.1:5000) as-is.
Security note: anything prefixed with
REACT_APP_is embedded into the built JavaScript bundle and is therefore visible to anyone who loads the site. Treat these as public keys and lock them down with origin / referrer restrictions in the Google Cloud Console.
Available npm scripts
| Script | What it does |
|---|---|
npm start | Start the React dev server on port 3000. |
npm run backend | Start the Flask backend (python app.py) on port 5000. |
npm run dev | Start the backend and frontend together via concurrently. |
npm run build | Produce a production build of the frontend in build/. |
npm test | Run the React test suite. |
Project layout
.
├── app.py # Flask backend entrypoint
├── backend/ # Additional backend modules
├── public/ # Static assets and HTML shell
├── src/ # React frontend source
├── requirements.txt # Python dependencies
├── package.json # Node dependencies + scripts
├── .env.example # Template for local environment variables
└── .gitignore
Analysis
View
Metric
- 9
- 6
- 4
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- FlaskIn code
- HTMLIn code
- JavaScriptIn code
- PythonIn code
- ReactIn code
6 of 6 appear in the indexed code.
AI coding agents
No AI coding agent signals were found in this repository.
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
38 KB
Source files
10
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
jonnypan2325/VroomMates
24 files · 929 KB · @ 88b6f27
Structure
Application logic
8 files · 33%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- JavaScript48%
- Python27%
- Markdown15%
- CSS8%
- HTML2%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
package.json
npm · 10- @react-oauth/google
- @testing-library/jest-dom
- @testing-library/react
- @testing-library/user-event
- axios
- react
- react-dom
- react-scripts
- web-vitals
- +1 more
requirements.txt
pypi · 3- Flask
- Flask-Cors
- python-dotenv
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Feature verification
Driver/passenger registration with capacityVerified
Users register as drivers or riders, input locations and destinations
Claimed on Devposthigh confidencesrc/LocationInput.js:4— UI state and forms for driver capacity/address and passenger address, submitted to backendapp.py:210— Backend parses driver/passenger location and capacity fields from the request
Flask backend for route optimizationVerified
Back end powered by Flask, Python handles clustering algorithms to generate optimized driver routes
Claimed on Devposthigh confidenceapp.py:186— Flask route /routeoptimizer/ (POST) validates input and calls give_paths() to compute optimized routes, returned as JSON
Frontend/backend split with REACT_APP_FLASK_API_URLVerified
Frontend talks to backend over HTTP; REACT_APP_FLASK_API_URL configures the backend URL
Claimed on readmehigh confidencesrc/LocationInput.js:179— Reads process.env.REACT_APP_FLASK_API_URL (falling back to localhost:5000) to construct the route optimizer request URL.env.example:17— Documents REACT_APP_FLASK_API_URL default value
Haversine formula for distance/clusteringVerified
Linear distance using the Haversine Formula to cluster drivers
Claimed on Devposthigh confidenceapp.py:10— haversine_distance() implements the great-circle distance formula and is used throughout the pathing and assignment logic
Location input via Google Maps/Places APIVerified
Front end uses Google Maps API for location input, tracking, and map display
Claimed on Devposthigh confidencesrc/LocationInput.js:77— Uses window.google.maps.places.Autocomplete for driver, passenger, and destination address inputsrc/App.js:50— Initializes a window.google.maps.Map instance and DirectionsRenderer for map displaypublic/index.html:14— Loads the Google Maps JavaScript API script with Places library
npm run dev runs backend and frontend concurrentlyVerified
npm run dev uses concurrently to start Flask backend and React dev server together
Claimed on readmehigh confidencepackage.json:15— dev script uses concurrently to run "npm run backend" and "npm run start" together, with backend script running python app.py
Rider-driver matching / assignment algorithmVerified
Automatically match riders with drivers based on optimal routes, minimizing detours
Claimed on Devposthigh confidenceapp.py:112— assign_drivers() implements a global-greedy bipartite assignment of passengers to drivers using pairwise detour cost, enforcing driver capacityapp.py:94— distance_from_line() computes detour cost used to score passenger-driver pairs
A* pathfinding for driver routesCode-supported
VroomMates uses A* for pathfinding to generate optimized driver routes
Claimed on Devpostmedium confidenceapp.py:53— Driver.get_path() uses a heapq-based best-first search over remaining passengers and destination, similar to A*/Dijkstra, but there is no explicit heuristic function, so it is closer to uniform-cost/Dijkstra search than a true A*
Google sign-inCode-supported
Users register/sign in (Google Login button visible in UI)
Claimed on Devpostmedium confidencesrc/App.js:17— useGoogleLogin from @react-oauth/google is wired to a login button and fetches profile info on success, but there's no backend session/auth enforcement tying this to route optimization access
React + Flask full-stack app with combined repo layoutCode-supported
Frontend (React, src/ and public/) and backend (Flask, app.py and backend/) in a single project
Claimed on readmemedium confidenceapp.py:1— Flask backend entrypoint exists as describedsrc/App.js:1— React frontend exists in src/ as described, but the backend/ directory mentioned in the README's project layout does not exist in this repo
Vercel hosting for frontendCode-supported
Hosted the app on Vercel
Claimed on Devpostlow confidence.vercelignore:1— A .vercelignore file exists configured to deploy only the React static site and exclude the Flask backend, implying a Vercel deployment setup, but no vercel.json or actual deployment evidence is present
Continuous deployment with GitHub ActionsClaimed only
Implemented continuous deployment with GitHub Actions and hosted on Vercel
Claimed on Devposthigh confidenceSession persistence via Google DatastoreClaimed only
Routes stored in Google Datastore, allowing users to save and resume sessions across devices
Claimed on Devposthigh confidence
An AI agent derived these features from the project’s Devpost page and readme, then searched the code for each one. Verified features are backed by cited code; claimed-only features had no supporting code, which is not by itself proof a feature is missing.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.