SyncRoute

SyncRoute matches carpool rides by road overlap and connects matching, booking and live trip events.

Two trips can share a destination while taking different roads, or share a useful segment while ending in different places. SyncRoute uses route geometry to compare the journey itself, then connects the match to segment pricing, seat booking and trip communication.

Preview · Quick start · Architecture · Development · Contributing

Application preview

Archived project capture showing the route-search form and an empty available-rides state.

Screenshot notes

Capabilities

Workflow	Result
Find a shared route	Compare actual road geometry rather than only destinations.
Book a segment	Connect a matched ride to pricing and booking records.
Follow a trip	Deliver trip and message events through the socket layer.

Quick start

Provision MongoDB and an OSRM endpoint. Configure private backend secrets and the frontend API, socket and map settings before running both processes.

From a fresh checkout:

git clone https://github.com/ryash14/SyncRoute.git
cd SyncRoute
cd syncroute-backend
npm install
# Configure .env with MONGODB_URI, JWT_SECRET, PORT and OSRM_SERVER.
npm start
# In another terminal: cd syncroute-frontend && npm install && npm run dev

Provision MongoDB and an OSRM endpoint. Frontend settings include VITE_API_URL, VITE_SOCKET_URL and VITE_MAPBOX_TOKEN. The documented development API port is 5000. External OCR, maps and messaging integrations require their own credentials. Production deployment must configure trusted origins, secrets and backing services.

Configuration

Process	Settings
Backend	MONGODB_URI, JWT_SECRET, PORT, OSRM_SERVER
Frontend	VITE_API_URL, VITE_SOCKET_URL, VITE_MAPBOX_TOKEN

Use http://localhost:5000/api for the local frontend API URL when the backend runs on port 5000, and http://localhost:5000 for the socket origin. Configure an OSRM endpoint compatible with the route utilities. Start both processes, create a small test ride and inspect search and booking separately; a successful map render does not verify seat reservations or live events.

Architecture and request flow

1. A passenger submits pickup and destination information.
2. The backend obtains route geometry and compares it with available rides.
3. Matching and pricing utilities produce ride candidates and segment costs.
4. Booking routes persist the reservation, while Socket.IO delivers live trip and messaging events.

Component model

flowchart TB
    Client["React maps and ride interface"] --> API["Express authentication and routes"]
    API --> Search["Ride search"]
    Search --> OSRM["OSRM road geometry"]
    OSRM --> Match["Overlap matching and segment pricing"]
    Match --> Candidates["Candidate rides"] --> Client
    API --> Booking["Booking workflow"]
    API --> Verify["Document verification"]
    Booking <--> DB[("MongoDB domain records")]
    Search --> DB
    Booking --> Events["Socket.IO trip and message events"]
    Events --> Client

Loading

Engineering decisions

The Express backend owns authentication, ride and booking routes, document verification and notification concerns. MongoDB persists domain records. OSRM provides routing geometry, and the React client presents maps and ride state.

Document OCR, provider-backed messaging and map services have their own configuration requirements. Match thresholds and business rules should be evaluated with real routes; a README threshold is not evidence of matching quality.

Implementation

Stack: Node.js · Express · MongoDB · Mongoose · OSRM · Socket.IO · React · TypeScript · Vite · OCR utilities.

• syncroute-backend/docs/ARCHITECTURE.md
• syncroute-backend/utils/rideMatchUtils.js
• syncroute-backend/server.js

Development

The hosted CI workflow currently references syncroute-backend/package-lock.json and syncroute-frontend/package-lock.json, which are not checked in. Its dependency-cache setup fails before the test jobs run. The local commands below are the available development checks; reviewed lockfiles are needed before the current npm ci workflow can run as written.

Run the repository checks after completing setup:

cd syncroute-backend && npm test
# Separately, from repository root:
# cd syncroute-frontend && npm test

Use the offline checks during development. Run provider-backed integration checks separately with configured credentials and representative inputs.

Contributing and support

Report reproducible bugs or propose changes through GitHub Issues. Include the relevant environment and a small example rather than private datasets or credentials. See contributing, security reporting and the code of conduct.

License

MIT. Existing third-party notices remain applicable.