RainRoute — An Explainable, Constraint-First Travel Agent

Inspiration

A beautiful itinerary is easy to recommend and surprisingly easy to break. A late arrival, sudden rain, or a closed venue can invalidate the day. Cultural affinity alone cannot tell a traveler whether a place is open, affordable, or reachable before closing. RainRoute makes those constraints visible and makes its decisions inspectable.

What it does

The runnable prototype takes a three-stop cultural itinerary and replans it when weather, delay, closure, budget, or the end time changes. It enumerates candidate routes, rejects every route that violates a hard constraint, ranks the feasible ones, and shows why the original route failed. When no route survives, it says so instead of inventing a recommendation. The interface covers a rainy day, a 90-minute delay plus a closure, a no-solution case, and a candidate-search failure state. Users can compare alternatives and adopt one in the current page session.

The current experience uses clearly labeled synthetic demo data: venue details, cultural scores, coordinates, hours, prices, and travel times are fixtures. A separate Qloo adapter implements entity search and place-insights requests with a server-side key. Live route generation deliberately stops until opening hours, prices, travel, and weather can be independently verified. Cultural discovery is never presented as proof that a venue is operationally feasible.

How we built it

RainRoute uses Node.js 20+, a small HTTP API, and a LangGraph state graph: resolve → discover → verify → replan → explain. Its planner checks budget, end time, opening hours, closure, and weather before ranking cultural fit. The Qloo boundary validates inputs, keeps the API key server-side, applies a timeout, and reports authentication, rate-limit, and network errors explicitly. A responsive desktop/mobile interface implements the visual design, including a checked 320px narrow-screen state.

Challenges we ran into

The hardest problem was keeping taste discovery separate from itinerary truth. A venue can be culturally appealing yet closed or impossible to reach. We made source status explicit, kept the demo deterministic, and block real-route output if independent venue facts are missing. Failure and no-solution states are core product behavior, not hidden exceptions.

Accomplishments that we're proud of

The prototype turns disruption into a reasoned, inspectable change: hard constraints stay hard, rejected alternatives remain explainable, and an impossible scenario produces an honest no-solution answer. All 9 automated tests passed on October 29, 2026, covering rain, combined disruptions, no-solution behavior, invalid input, Qloo request handling, and the guard against unverified live routes. The interface supports four scenario states and a 320px layout check.

What we learned

An agentic experience earns trust when it can refuse a route for a precise reason. Cultural discovery and real-world feasibility need distinct sources, validations, and status labels.

What's next

Validate Qloo requests against authorized live responses, add independently sourced venue facts, and run end-to-end live-route checks. The public repository and synthetic-data browser demo are available below. A video walkthrough remains to be recorded.

English interface and testing walkthrough: RainRoute demo guide.

Builder's engineering record

FOWEPJF255 has merged upstream fixes in Microsoft Agent Framework checkpoint state, Turborepo's bounded cache fallback, OpenHands' narrow-screen plugin search, and LMDeploy's async migration completion. These public contributions show the builder's engineering background; they are separate from RainRoute's features.

Built With

• css
• html
• javascript
• langgraph
• node.js
• qloo