Revenue Route

Landing Page
Landing Page
Landing Page
Landing Page
Landing Page

Inspiration

Field workers in Ho Chi Minh City face a daily logistics puzzle: they have 5–30 stops to make, scattered across the city, with different clients, time windows, and priorities. Yet most still plan their routes by gut feeling — opening Google Maps one stop at a time, scribbling appointment notes on Zalo or in a notebook, with no single tool that brings it all together.

We built Revenue Route because we saw real people losing 1–3 hours every single workday to inefficient movement. A real estate broker juggling viewings for multiple clients can't afford to ping-pong across the city. A B2B sales rep shouldn't have to mentally compute the optimal visit order before 8am. We believed that combining AI reasoning with geospatial data could solve this in a way no existing tool had — not just "shortest path between two points," but a full-day optimized plan that respects priorities, client groupings, time constraints, and Ho Chi Minh City's notoriously congested traffic patterns.

What it does

Revenue Route turns a messy list of daily appointments into a structured, AI-optimized itinerary:

Appointment Logging — Add stops anytime throughout the week with details like address, client name, time window, priority, and estimated visit duration. Input by form or by typing in natural language ("Meet Anh Tuan at Cho Ray Hospital Thursday at 10am, 30 minutes, high priority").
Client Grouping — Appointments for the same client are automatically kept together in the itinerary — no ping-ponging between clients mid-day.
One-tap AI Optimization — On the day of work, hit "Optimize Route." The AI backend geocodes all stops, computes a real-time distance matrix factoring in traffic, and uses an LLM to produce the optimal visit order with a written explanation of its reasoning.
Interactive Timeline — View a detailed, grouped timeline showing estimated arrival times, travel legs, and client groups — all in one glance.
AI Chat Adjustments — Chat naturally to refine the plan: "Anh Tuan cancelled, remove his group," "Add a stop in Thu Duc for Chị Mai," "Switch to car, recalculate."
Navigation Integration — Tap any stop to open Google Maps for turn-by-turn directions.
Check-in Checklist — Mark stops as completed as you go.

How we built it

Revenue Route is a full-stack web application with a decoupled frontend and AI-powered backend:

Frontend

Built with Next.js 16 (App Router) and TypeScript, styled with Tailwind CSS v4 and shadcn/ui component library. Accessible interactive primitives come from React Aria. Client state is managed with Zustand, server state with TanStack Query, and forms are validated with React Hook Form and Zod. The map view is powered by OpenStreetMap via Leaflet.

Backend

Built with FastAPI (Python), orchestrated through a LangGraph agentic pipeline. The AI reasoning layer uses OpenAI GPT with function calling to act as a route planner — it calls geocoding tools, requests a distance matrix, checks traffic patterns, applies client grouping constraints, respects time windows, and then produces an ordered itinerary with a human-readable explanation.

AI Pipeline Architecture

User Input → LangGraph Workflow
               ├── Geocode all stops (Google Maps API)
               ├── Build distance + duration matrix (Google Maps Distance Matrix API)
               ├── Apply traffic context (departure time, HCM congestion patterns)
               └── LLM (GPT) → Optimal ordered plan + AI explanation → JSON Response

Database

PostgreSQL with SQLAlchemy (async) and Alembic for schema migrations stores appointments, route plans, and chat history.

Challenges we ran into

Client grouping as a hard constraint — Standard TSP solvers optimize purely for distance. Enforcing that all stops for a given client must be consecutive — without splitting groups — required careful prompt engineering and validation logic in the LangGraph pipeline.
LLM reliability for structured output — Getting the LLM to consistently output valid, well-formed JSON route plans (not just text) under varying input sizes required iterative prompt design and output schema enforcement via Pydantic.
Ho Chi Minh City traffic modeling — Google Maps Distance Matrix handles real-time travel times, but we also needed to encode domain knowledge (known congested corridors by time-of-day) directly into the LLM system prompt to improve scheduling quality even when API data is approximate.
Natural language parsing into structured appointments — Building a robust /api/parse-text endpoint that can take a freeform Vietnamese or English sentence and extract a fully structured appointment object required careful few-shot prompting and post-processing validation.
Full-stack integration under hackathon time pressure — Coordinating a Next.js frontend with a FastAPI + LangGraph backend, keeping the API contract stable across both teams, and iterating quickly required disciplined documentation and clear interface boundaries from day one.

Accomplishments that we're proud of

End-to-end AI pipeline from raw text input to a fully optimized, grouped, time-aware itinerary — all in under 30 seconds.
Client grouping constraint correctly enforced in AI output — a non-trivial scheduling requirement that existing tools don't handle.
Natural language appointment entry that parses Vietnamese and English freeform input into structured data using an LLM.
AI-powered chat interface for real-time route adjustments — add/remove stops, change constraints, switch transport mode — all through conversational interaction.
A clean, responsive production-quality UI with dark mode, i18n support, and animated visualizations — built in a single hackathon sprint.

What we learned

LangGraph is powerful for multi-step AI workflows — structuring the optimization as a directed graph (gather data → geocode → compute matrix → LLM decide → validate output) made the pipeline far more reliable and debuggable than a single monolithic LLM call.
Prompt engineering is engineering — defining clear constraints (like client grouping), providing domain context (HCM traffic), and enforcing output schemas required the same rigor as writing application code.
Mocking external APIs early is essential — building a Haversine-based mock for Google Maps Distance Matrix from day one meant the entire team could develop and test without API keys or costs, and integration was seamless later.
Clear API contracts unlock parallel development — defining the four API endpoints in a shared spec document before writing any code allowed frontend and backend to build independently and integrate with minimal friction.

What's next for Revenue Route

Live traffic integration — Full production switch to Google Maps Distance Matrix API with real-time departure-time-aware routing.
Mobile PWA — Progressive Web App packaging for an app-store-like experience on iOS and Android, optimized for use while in the field.
Team collaboration — Multi-user support for sales managers to view and coordinate their team's daily routes.
CRM integration — Connect with popular CRM platforms (Salesforce, HubSpot, local Vietnamese tools) to automatically import appointments and sync visit outcomes.
Historical analytics — Track actual vs. planned routes, time savings, and visit completion rates to continuously improve AI recommendations.
Multi-city expansion — Extend beyond Ho Chi Minh City with city-specific traffic models for Hanoi and other Vietnamese cities.
Recurring route templates — Save common route patterns for repeat visits (e.g., weekly client check-ins) with one-tap optimization.