Inspiration
RippleRoute — AI-Powered Freight Routing & Disruption Recovery
When supply chains break, RippleRoute finds a better way.
Live Demo: Try RippleRoute
GitHub Repository: View Source Code
Inspiration
What happens when every shipment takes its fastest route, but the transportation network cannot handle all of them?
That question inspired RippleRoute.
Navigation applications are great at finding the fastest or cheapest route between two locations. However, freight transportation introduces a more complicated challenge. Multiple shipments share the same infrastructure, transportation connections have limited capacity, and unexpected disruptions can make previously valid routes unavailable.
A route that works perfectly for one shipment might create a bottleneck when several shipments attempt to use it simultaneously.
I wanted to explore how graph algorithms, capacity-aware planning, interactive visualization, and generative AI could work together to make transportation disruptions easier to understand and respond to.
As this was my first hackathon, I also wanted to challenge myself to build and deploy an end-to-end application that goes beyond displaying data and actually demonstrates meaningful algorithmic decisions.
That led me to build RippleRoute, an interactive freight resilience simulator that helps users explore disruptions, compare transportation routes, coordinate multiple shipments, and understand recovery decisions through AI-powered explanations.
What It Does
RippleRoute simulates an industrial transportation network consisting of:
- 10 fictional transportation hubs
- 17 directed connections
- 5 steel shipments
- Different shipment priorities and delivery deadlines
- Limited transportation capacity
- Dynamic infrastructure disruptions
Every transportation connection has a travel time, transportation cost, and cargo capacity.
RippleRoute provides three main experiences.
1. Network Universe — Explore the Transportation Network
Network Universe provides an interactive spatial visualization of the transportation system.
Users can explore connected hubs, inspect transportation routes, select locations, and visualize paths through the network.
The interface includes dimensional nodes, curved connections, contextual highlighting, camera focus, panning, and zooming.
Instead of presenting a static network diagram, RippleRoute makes the graph interactive and easier to understand.
2. Disruption Lab — Simulate Failures and Coordinate Shipments
Disruption Lab is the central feature of RippleRoute.
It supports two planning modes.
Single Shipment Planning
Users can:
- Select an origin and destination.
- Compare the fastest and lowest-cost routes.
- Simulate infrastructure disruptions by closing hubs.
- Recalculate available routes after a disruption.
- Compare travel duration and transportation cost.
When a hub becomes unavailable, RippleRoute excludes it from the routing calculation and searches for another feasible path.
Fleet Planning
Fleet Planning goes beyond individual route optimization.
Instead of treating shipments independently, RippleRoute coordinates five shipments that compete for shared transportation capacity.
The application considers:
- Shipment priorities.
- Delivery deadlines.
- Cargo quantities.
- Candidate routes.
- Remaining transportation capacity.
- Route duration and cost.
The interface displays capacity conflicts, coordinated reservations, rerouting decisions, delivery outcomes, and transportation costs.
Users can also follow a simulated shipment along its assigned route.
A Capacity Conflict in Action
One baseline scenario demonstrates why fleet coordination matters.
Two shipments independently select the connection from Central Junction to Union Depot.
- RR-2048: 35 tonnes.
- RR-2050: 70 tonnes.
- Combined independent demand: 105 tonnes.
- Available capacity: 90 tonnes.
The overloaded demand is:
$$ 35 + 70 = 105 \text{ tonnes} $$
The capacity shortage is:
$$ 105 - 90 = 15 \text{ tonnes} $$
Although both individual routes may appear reasonable, their combined demand exceeds the connection's available capacity.
When the user clicks Coordinate Fleet, RippleRoute evaluates the shipments together.
In the baseline scenario:
- RR-2048 takes an alternative feasible route.
- RR-2050 retains the original connection.
- The coordinated reservation becomes 70 out of 90 tonnes.
- All five shipments receive assignments.
The remaining connection capacity is:
$$ 90 - 70 = 20 \text{ tonnes} $$
The key insight is that finding good individual routes does not automatically produce a feasible fleet-wide transportation plan.
3. Decision Replay — Understand Previous Decisions
Decision Replay allows users to revisit recorded simulation events and examine previous routing or disruption decisions.
Instead of showing only the final outcome, RippleRoute helps users understand how the simulated transportation scenario changed.
This makes routing decisions easier to inspect, explain, and demonstrate.
AI Explanations and Voice Briefings
RippleRoute integrates Google Gemini and ElevenLabs.
Google Gemini generates natural-language explanations of computed routing results, capacity conflicts, and recovery decisions.
ElevenLabs converts briefing text into spoken audio.
Importantly, AI does not calculate or invent the transportation routes.
The routing and fleet allocation decisions are produced by deterministic algorithms. Gemini helps explain the results, while ElevenLabs provides audio narration.
How I Built It
RippleRoute is a full-stack web application built using React, TypeScript, Vite, Node.js, and Express, with integrations for Google Gemini and ElevenLabs.
Technology Stack
Frontend
- React
- TypeScript
- JavaScript
- Vite
- HTML5
- CSS3
- SVG-based interactive visualizations
Backend
- Node.js
- Express.js
- TypeScript
- Zod for validation
- esbuild for server bundling
Algorithms
- Dijkstra's shortest-path algorithm
- Directed weighted graph modeling
- Candidate route enumeration
- Capacity-aware greedy fleet allocation
- Shipment priority and deadline ordering
- Shared-capacity reservations
AI and Voice
- Google Gemini API
- ElevenLabs API
Deployment and Development
- Vercel
- Git
- GitHub
- Automated regression testing
Frontend Architecture
The frontend uses React and TypeScript, with Vite handling local development and production builds.
React manages the interactive user interface, and TypeScript provides typed application logic.
The frontend includes:
- Interactive transportation-network visualization.
- Origin and destination selection.
- Routing objective selection.
- Hub disruption and restoration controls.
- Fleet coordination and capacity-conflict visualization.
- Before-and-after allocation comparisons.
- Animated shipment progress.
- Shipment deadlines, costs, and reservations.
- Gemini analysis controls.
- ElevenLabs audio playback.
- Decision history and replay.
Shared React state coordinates selected hubs, closed infrastructure, routing objectives, shipment assignments, and simulation events across the application.
The visualizations respond to computed simulation results rather than relying on predetermined successful outcomes.
Graph Modeling and Dijkstra's Algorithm
The transportation network is represented as a directed, weighted graph.
Mathematically, the graph can be written as:
$$ G = (V, E) $$
Where:
- (V) represents the transportation hubs.
- (E) represents the directed connections between hubs.
Every directed connection includes:
- Travel time in hours.
- Transportation cost in USD.
- Maximum cargo capacity in tonnes.
For single-shipment planning, I implemented Dijkstra's shortest-path algorithm.
The algorithm finds a minimum-weight path between the selected origin and destination.
Depending on the selected objective, the edge weight represents travel time or transportation cost.
For a path (P), total travel time is:
$$ T(P) = \sum_{e \in P} \text{hours}(e) $$
Total transportation cost is:
$$ C(P) = \sum_{e \in P} \text{cost}(e) $$
The fastest-route objective is:
$$ \min_{P} T(P) $$
The lowest-cost-route objective is:
$$ \min_{P} C(P) $$
The algorithm considers available directed connections, checks route feasibility, and reconstructs the selected path.
When a hub is closed, routes passing through that hub are excluded from consideration.
For the baseline shipment example:
- Fastest route: 35 hours, $1,770.
- Lowest-cost route: 37 hours, $1,570.
This illustrates a tradeoff between delivery speed and transportation cost.
The faster route saves two hours, while the cheaper route saves $200.
Capacity-Aware Fleet Allocation
The most important algorithmic component of RippleRoute is its capacity-aware greedy fleet allocator.
Traditional shortest-path algorithms optimize one shipment at a time.
However, when several shipments use the same network, their independently selected routes may compete for limited infrastructure capacity.
RippleRoute addresses this through shared-capacity reservations.
The allocator processes shipments in the following priority order:
- Critical-priority shipments.
- High-priority shipments.
- Normal-priority shipments.
Within the same priority level, shipments with earlier deadlines are processed first.
Shipment ID provides deterministic tie-breaking.
For each shipment, the allocator:
- Generates or considers candidate directed routes.
- Checks the remaining capacity of every connection.
- Evaluates delivery deadlines and routing preferences.
- Selects a feasible route according to the chosen objective.
- Reserves the required cargo quantity on the selected connections.
- Updates remaining capacity before processing the next shipment.
For any directed connection (e), the capacity constraint is:
$$ R_e \leq K_e $$
Where:
- (R_e) is the total reserved cargo on connection (e).
- (K_e) is the maximum cargo capacity of connection (e).
For the set of assigned shipments (S_e) using that connection:
$$ R_e = \sum_{s \in S_e} q_s $$
Here, (q_s) represents the cargo quantity of shipment (s).
The allocator tracks the remaining capacity:
$$ A_e = K_e - R_e $$
Where (A_e) is the remaining available capacity on connection (e).
This prevents the coordinated allocation from overbooking the modeled infrastructure.
Fleet Planning Objectives
RippleRoute provides two fleet-planning objectives.
Fastest Feasible
The allocator prefers:
- Routes meeting delivery deadlines.
- Shorter travel time.
- Lower transportation cost.
- Deterministic route-ID tie-breaking.
Lowest Feasible Cost
The allocator prefers:
- Routes meeting delivery deadlines.
- Lower transportation cost.
- Shorter travel time.
- Deterministic route-ID tie-breaking.
Both objectives use the same shipment-priority ordering and capacity checks.
The selected objective changes which candidate routes are preferred, not the physical capacity of the network.
Why a Greedy Heuristic?
The fleet allocator uses a deterministic greedy heuristic.
It makes assignments one shipment at a time, updating remaining infrastructure capacity after each decision.
This approach provides practical, reproducible allocations for the simulated network.
However, it does not guarantee a globally optimal solution across every possible combination of shipment assignments.
The current model also uses a shared 48-hour dispatch planning cohort rather than detailed real-time capacity scheduling.
Independent Demand Versus Coordinated Reservations
RippleRoute distinguishes between two concepts.
Independent demand represents the transportation capacity shipments would request if they selected routes without considering other shipments.
Coordinated reservations represent the capacity actually assigned through fleet-level planning.
Independent demand may exceed a connection's capacity.
Coordinated allocation tracks remaining capacity and avoids overbooking within the modeled constraints.
This distinction powers the application's before-and-after recovery visualization.
Backend Architecture — Node.js and Express
The backend uses Node.js and Express to provide API endpoints for external integrations.
It handles:
- Incoming API requests.
- Request validation.
- Routing-result consistency checks.
- Communication with external AI providers.
- Response validation.
- Audio generation requests.
- Error handling.
Keeping external API integrations on the server helps protect sensitive credentials from being exposed in frontend code.
The architecture separates deterministic transportation calculations from generative AI explanations.
As a result, the core route-planning simulation does not depend on Gemini or ElevenLabs being available.
Google Gemini Integration
Gemini acts as an AI-powered dispatch advisor.
After RippleRoute calculates a route or fleet allocation, Gemini can generate a plain-language explanation of the results.
The backend validates relevant routing information to help ensure the explanation remains consistent with the computed scenario.
For example, Gemini can explain:
- Why a capacity conflict occurred.
- Which shipment was rerouted.
- How the coordinated plan differs from independent routing.
- What travel-time and cost tradeoffs resulted.
Gemini explains the calculated decisions rather than choosing the routes itself.
ElevenLabs Integration
ElevenLabs adds voice generation to RippleRoute.
Users can generate spoken audio from briefing text and listen directly within the application.
This helps make complex transportation decisions easier to communicate.
Gemini and ElevenLabs requests are initiated through explicit user actions rather than running automatically when the page loads.
Deployment and Testing
RippleRoute is deployed on Vercel and its source code is hosted on GitHub.
The frontend is built with Vite, and the backend is bundled for deployment using esbuild.
During development, I tested routing calculations, capacity allocation, scenario handling, and frontend interactions.
The final pre-submission version passed 90 automated tests and production build validation.
I also checked responsive behavior, network interactions, page scrolling, visual consistency, and navigation across the application.
Challenges I Faced
1. Going Beyond Single-Shipment Routing
Initially, the problem appeared to involve finding the fastest route between two hubs.
However, I realized that independently optimized routes could compete for shared infrastructure and create infeasible fleet plans.
Introducing capacity-aware allocation required thinking about the entire network and all shipments together.
2. Managing Priorities, Deadlines, and Limited Capacity
Different shipments have different cargo quantities, priorities, and delivery deadlines.
At the same time, the remaining capacity of a connection changes after each assignment.
Building a deterministic allocation strategy that accounts for these constraints was a major technical challenge.
3. Making Complex Algorithms Easy to Understand
Graph algorithms and capacity constraints can be difficult to communicate.
Early interface versions included compressed network visualizations, small text, and too much technical information.
I iteratively refined the application with clearer visual hierarchy, route highlighting, larger typography, and before-and-after comparisons.
I learned that an effective visualization should explain a decision rather than simply look impressive.
4. Reliable AI Integration
Integrating Gemini introduced challenges involving response validation and consistency with computed results.
I wanted AI to explain reliable algorithmic decisions, not invent transportation routes or capacity values.
Separating deterministic calculations from generative AI explanations became an important design principle.
ElevenLabs integration also involved backend requests, audio playback, and error handling.
5. Deployment and External Services
Deploying the complete application involved frontend builds, backend bundling, server-side integrations, and production debugging.
I also explored PostgreSQL and Tiger Data for persistent storage but encountered a TLS certificate-chain issue during database connectivity testing.
Rather than weakening security or relying on an unverified connection, I kept persistent database storage separate from the core working demonstration.
6. Building Under a Hackathon Deadline
As this was my first hackathon, I gained experience managing an entire software development process under time constraints.
I worked through implementation, testing, interface design, debugging, deployment, and presentation preparation.
This taught me the importance of prioritization, incremental development, and maintaining a working application while making improvements.
Accomplishments I'm Proud Of
My biggest accomplishment is demonstrating how capacity-aware fleet coordination can resolve problems that independent shortest-path planning fails to address.
In addition, I:
- Implemented Dijkstra's shortest-path algorithm.
- Developed a deterministic capacity-aware fleet allocation heuristic.
- Supported dynamic hub disruptions and route recalculation.
- Built an interactive transportation-network interface.
- Visualized coordinated reservations and rerouting decisions.
- Integrated Google Gemini for grounded explanations.
- Integrated ElevenLabs for voice briefings.
- Built and deployed a complete full-stack application.
- Passed 90 automated tests before submission.
Most importantly, I transformed a technical routing problem into an understandable and interactive experience.
What I Learned
Graph Algorithms
I learned how directed weighted graphs, shortest-path algorithms, and route reconstruction can model transportation decisions.
Optimization and Constraints
I learned why independently optimal routes may not produce a feasible fleet plan and how a greedy allocator can handle shared capacity.
Frontend Engineering
I improved my understanding of React, TypeScript, shared state, interactive visualization, animation, and responsive design.
Backend Development
I gained experience with Express APIs, request validation, server-side integrations, and environment-based configuration.
Generative AI
I learned the importance of grounding AI-generated explanations in reliable computational results.
Deployment and Testing
I gained experience debugging production builds, testing application behavior, and deploying a full-stack application.
User Experience
One of my biggest lessons was that technical correctness is only part of building a useful product.
Users also need to understand what the system is doing and why its decisions matter.
What's Next for RippleRoute?
RippleRoute currently demonstrates freight coordination through a fictional transportation network.
Future improvements could include:
- Real transportation infrastructure and logistics datasets.
- Time-dependent capacity reservations.
- Scheduled departures and resource availability.
- More advanced optimization algorithms.
- Integer programming and min-cost flow formulations.
- Larger transportation networks and shipment cohorts.
- Persistent scenario histories and collaborative planning.
- Realistic travel delays and uncertainty modeling.
- More detailed comparisons between alternative recovery strategies.
Ultimately, I'd like to explore how deterministic optimization and AI-assisted communication can work together to improve transportation disruption planning.
Final Takeaway
RippleRoute demonstrates that finding a good route is only the beginning. The real challenge is making multiple routes work together when infrastructure, capacity, and deadlines are limited.
By combining graph algorithms, capacity-aware fleet allocation, interactive simulation, Gemini explanations, and ElevenLabs voice briefings, RippleRoute makes complex freight coordination easier to explore and understand.
Live Project: RippleRoute
Source Code: GitHub Repository
What it does
How we built it
Challenges we ran into
Accomplishments that we're proud of
What we learned
What's next for RippleRoute
Built With
- css3
- dijkstra's
- elevenlabs
- express.js
- github
- google-gemini
- html5
- javascript
- node.js
- react
- typescript
- vercel
- vite
Log in or sign up for Devpost to join the conversation.