Multicit

Travel planner chatbot with curated data layers, LangGraph states, and flight search API.

🔒 Source code is private

Multicit

Multi-city trip composition: fly in, travel overland, fly out. In development; nothing is deployed yet.

Multicit is built for one kind of trip: fly into one airport, cross a built-up region overland, and fly home from another (A→B, B~C, C→D). The scope is Europe, Turkey and Cyprus, the Caucasus, the Levant, South, East and South-East Asia, and Egypt, Morocco and Tunisia. Two independent products serve that trip from one website. flight finds open-jaw fare combinations ranked by how much cheaper than usual they are, with deep links so the traveller checks each price at the source. plan proposes a route between the arrival and departure endpoints (stops, nights, ground legs) on a map, and lets the traveller edit it, keep every revision and branch from any of them; conversational editing arrives at P3. Both stand on two shared foundations: globe, a curated geographic dataset, and trip, a deterministic route engine. Correctness beats coverage, and the model proposes while the engine decides.

This repository is the multicit.com site (run and deploy notes). The product repositories are private; they are linked below as proof of the architecture, and access is available on request.

Architecture

Five repositories, split by charter. They couple through contracts and running services, never through shared code:

A data release. globe publishes an immutable release that flight loads as a PostGIS geo schema and trip reads as a globe-bundle/1 MessagePack bundle. Consumers pin it by hash and verify it on load.
A library. plan runs trip in-process: a NAPI addon on Node, a WASM module in its Cloudflare Worker.
One HTTP envelope. flight’s client asks the trip-edge Worker for a route preview over trip-edge/2.

Design: system architecture · vision and roadmap · trip routing · flight architecture · plan architecture.

Layer	Responsibility
Reference data (`globe`)	A Go builder fetches OurAirports, GeoNames, Natural Earth, Wikidata, GTFS and OSM into a content-addressed cache, then builds offline into a release `geo-YYYY.MM.N` identified by `content_hash` and `artifact_hash`. It also ships the Rust `globe-geo` reader (wasm32-ready), a TypeScript map kit (one declarative `LayerSpec` drawn by d3 and MapLibre adapters), an ODbL road layer routed with Valhalla, and an explorer for judging each release by eye
Engine (`trip`)	A pure Rust engine with no I/O, no clock and no unseeded randomness: corridor lens, k-best layered dynamic-programming search, night allocation, validation and scoring, typed mutations and stop locks. Shipped as a NAPI addon, a WASM module, and `trip-edge`, a stateless Cloudflare Worker with an edge cache
Fares (`flight`)	A Go service. A Postgres attempt ledger admits every provider call against a budget, with SearchAPI as the production source behind a provider port. Raw captures are stored by SHA-256, fare facts go to partitioned Postgres, and versioned reading rules pick cheapest and best. Search reads only that cache. React client
Planner (`plan`)	TypeScript use cases behind ports, served by Hono on two runtimes: Node over Postgres, and a Cloudflare Worker over D1. Idempotent commits with a revision compare-and-swap, forks from any revision, exact replay. React and MapLibre client
Site (`web`, this repository)	The Astro site on Cloudflare Pages; the only thing that links flight and plan

┌─ SOURCES ─────────────────────────────────────────────────────────────────────┐
│  OurAirports · GeoNames · Natural Earth · Wikidata · GTFS · OpenFlights · OSM │
└──────────────────────────────────────┬────────────────────────────────────────┘
                                       │ content-addressed fetch → offline build
                                       ▼
┌─ GLOBE ─ immutable release geo-YYYY.MM.N ─────────────────────────────────────┐
│  geo schema · globe-bundle/1 + road layer · map kit for both front-ends       │
│  identified by content_hash + artifact_hash; consumers pin and verify         │
└─────┬──────────────────────────────────────────────────────────┬──────────────┘
      │ pinned bundle                                            │ pinned schema
      ▼                                                          ▼
┌─ TRIP ─ Rust engine ────────────┐                ┌─ FLIGHT ─ Go · PostGIS ────┐
│  suggest · mutate · validate    │  trip-edge/2   │  budgeted crawl            │
│  NAPI · WASM · trip-edge Worker │ ─────────────► │  → captures → fare facts   │
└─────┬───────────────────────────┘ route previews │  search reads the cache    │
      │ in-process                                 └─────────────┬──────────────┘
      ▼                                                          │
┌─ PLAN ─ TypeScript · Hono ──────┐                              │
│  Node + Postgres · Worker + D1  │                              │
│  revisions · forks · replay     │                              │
└─────┬───────────────────────────┘                              │
      ▼                                                          ▼
┌─ MULTICIT.COM ─ links the two products; no data passes between them ──────────┐
└───────────────────────────────────────────────────────────────────────────────┘

Why this shape.

Contracts, not shared code. Pinned data, a library contract and one HTTP envelope are the only couplings. flight and plan never call each other, and either is complete without the other.
The data is half the product. globe is curated against sources, not scraped and trusted: claims are sourced and dated, unmeasured durations stay null, 6,797 city-subdivision pairs were judged one by one into reversible groupings, and share-alike data stays out of the clean release.
Deterministic and provenance-stamped. The same inputs build the same content_hash. The same request, bundle and policy hashes give a byte-identical route natively and under WASM: the objective is integer-only, and clippy bans HashMap and std float maths. Every plan carries its data and engine identities, and plan replays any command byte for byte.
The model proposes, the engine decides. Words become typed mutations that the engine applies atomically or rejects.
Store facts, read by rules; report honestly. flight keeps every returned itinerary and reads it through versioned rules, so a rule can change without re-collecting. trip reports SearchIncomplete, not Unroutable, when a search was truncated, and nothing invents minutes, dates or clock times.
Boundaries are enforced, not documented. golangci depguard layer rules in flight; a lint-enforced MVC split and a runtime-neutral core in plan; schema drift gates; and an offline deploy-check that refuses stale, fixture or tampered packages.

Selected figures

Taken from committed release notes and measurement records. Timings are local runs on the recorded host, not production.

	Figure	Record
Dataset	9,056 airports, 32,870 cities and 8,720 metros worldwide	release `.6`
MVP region	2,450 airports and 17,550 cities in a 2.89 MB bundle (budget 3 MB)	release `.6` · `.10.1`
Road layer	109,196 of 112,284 planned directed pairs routed with Valhalla over OSM	release `.10.1`
Host parity	14 requests answered byte for byte alike by NAPI and workerd	T3.11 parity
Graph query	Nonstop query at 0.52 ms best warm against a < 100 ms gate	F1 review
Planner gates	615 unit, 418 Node and 234 workerd tests; 15 of 15 judged routes Valid on both runtimes	P2 steps

Tech stack

Data pipeline: Go 1.26 · pgx · Postgres 17 + PostGIS 3.5 · Valhalla + osmium · PMTiles / Protomaps · MessagePack
Engine: Rust 1.97 (edition 2024) · serde · libm · NAPI-RS · wasm-bindgen · proptest · criterion
Fares: Go · pgx · sqlc · goose · chromedp · SearchAPI
Planner: TypeScript 6 · Hono · Postgres · Ajv + schema-generated types; LangGraph.js chat planned for P3
Front-ends: React 19 · Vite 8 · MapLibre GL + PMTiles · d3-geo · Astro (this site)
Edge: Cloudflare Workers + D1 (plan, trip-edge) · Cloudflare Pages (site) · wrangler · Miniflare / workerd
Quality: Docker Compose behind Make, no host toolchains · Vitest · Playwright + axe-core · golangci-lint (depguard) · clippy · ESLint boundary rules · schema drift gates · Wasmtime

Roadmap

Each repository keeps its own ladder (globe · trip · flight · plan), and a milestone closes at a reviewed pause on recorded evidence. plan deploys first, after P3; trip-edge deploys with the flight side.

Milestone	Capability	Status
G1 - Dataset build	Countries, airports, cities, metros and regions from locked sources, built deterministically and verified	✅ Done
G2 - Explorer and map kit	The map kit, the explorer, the `eurasia` MVP region and judged city groupings	✅ Done
G3 - Ground minutes	Sourced ground durations, then a bus and road tranche with an OSM road layer routed by Valhalla	✅ Done (`geo-2026.10.1`)
G4–G5	Points of interest; a monthly release cadence	Planned
T1 - Domain	The trip document, evidence, night allocation, validation and the mutation catalogue	✅ Done
T2 - Routes	Corridor search, ranking and alternatives, closed against five golden trips	✅ Done
T3 - Edge and locks	trip-wasm, the trip-edge Worker, host parity, road-layer adoption, stop locks and allocation modes	✅ Done (edge not yet deployed)
T4–T6	Enumeration and further generators, an offline TripPack, UniFFI bindings	Planned
F1 - Consume geo	The pinned `geo` schema in PostGIS, graph queries and a one-command bump	✅ Done
F2 - Crawl	Budget-admitted collection, captures, fare facts and readings, a dev airport picker, SearchAPI	In progress: F2.1–F2.6 built; infrastructure and a seven-day run remain
F3–F4 - Search and MVP	Cache-only multi-city search and scoring; the free-tier MVP, local first	Planned
F5–F7	Baselines and cadence, production launch, route previews from trip-edge	Planned
P1 - Route on a map	Endpoints and dates in, a validated route with stops, nights and ground legs on a map, on Node and on the Worker	✅ Done
P2 - Editing and branches	Route edits as typed mutations, stop and night locks, saved revisions, forks and exact replay	✅ Done
P3 - Conversation	LangGraph chat that proposes edits, durable runs and cost tracking; then plan’s first deploy	Next
P4–P6	Grounding, days and points of interest, bring-your-own-key and TripPack export	Planned
Site	The multicit.com placeholder; product pages arrive with plan’s first deploy	Placeholder

Keywords

Languages: Go · Rust · TypeScript · SQL
Architecture: Multi-Repository · Contract-First · Hexagonal Ports and Adapters · Deterministic Builds · Content-Addressed Releases · Provenance Stamping · Runtime-Neutral Core · Edge Computing
Geodata: Geospatial ETL · PostGIS · Curated Reference Data · Evidence Ledger · Licence Partitioning (ODbL) · OSM Road Routing (Valhalla) · Vector Tiles (PMTiles)
Engine: Route Search (k-best DP) · Typed Mutations · Integer Objective · WebAssembly · NAPI · Byte-Identical Cross-Host Parity · Golden Trips
Fares: Budget-Admitted Crawling · Append-Only Captures · Store Facts, Read by Rules · Fenced Work Queue
Planner: Idempotent Commits · Optimistic Concurrency · Branching Revision History · Exact Replay · Cloudflare Workers + D1
Quality: Docker-Only Toolchains · Lint-Enforced Boundaries · Schema Drift Gates · Property Testing · Playwright E2E · Accessibility Checks (axe)