Modern Logistics and Delivery systems rely heavily on one core capability: Calculating distances and travel times (Distance Matrix) quickly and accurately.
How does Grab dispatch millions of drivers every second? How does ShopeeXpress optimize delivery routes for tens of thousands of couriers simultaneously? The secret lies in Routing Engine and Geospatial Indexing architecture.
In this 8-part series, we will examine building a complete Distance Matrix API and Routing Engine using Golang, integrated with Graphhopper, and accelerated by Redis and Uber’s H3 Indexing. This series is designed to be highly visual, starting from scratch (understanding algorithms visually) all the way to large-scale load testing architecture.
🗺️ Series Contents (8 Parts)#
Q&A: Frequently Asked Questions#
Is this series suitable for beginners?#
Absolutely. The series is designed with a “Foundation First” philosophy. Parts 1 and 2 thoroughly explain concepts through visuals and provide step-by-step environment setup instructions (downloading OSM map data, running Docker) so anyone can follow along.
Why combine Golang and Graphhopper?#
Golang provides excellent concurrency and a small footprint, making it ideal as an API Gateway. Meanwhile, Graphhopper (written in Java) is an incredibly powerful routing engine. This combination brings out the best of both worlds: Golang handles I/O and Caching, while Graphhopper handles deep algorithmic computations.
Will the source code of the Demo Repo be shared?#
Yes. The entire source code, Docker Compose configuration, sample OpenStreetMap data files, and K6/JMeter test scripts will be publicly available on a companion GitHub repository.
Related Posts: GraphHopper in Production#
Practical deployment guides that extend the series into real production environments:
Pillar Architecture Guide: This article is part of the Multi-region Geo-distributed API Routing Architecture series. Please refer to the original article for a comprehensive overview of the architecture.
Prerequisite: This is the executive summary and introductory overview of the Routing & Geospatial Architecture series. No prior reading is required to start here.
Executive Summary: Geospatial & Routing Architecture Executive Summary & Quick Answer: High-concurrency routing systems combine Java-based GraphHopper engines for Contraction Hierarchies pathfinding with a Golang API Gateway using Uber H3 hexagonal indexing and Redis semantic caching. This architecture resolves 100x100 distance matrices in under 30ms while reducing compute load by up to 95%.
...
Answer-First: Zero-downtime Kubernetes deployments for routing services combine Argo Rollouts canary strategies, pre-stop hook draining, and automated P99 latency validation.
Pillar Architecture Guide: This article is part of the GitOps at Scale: Kubernetes & ArgoCD for Microservices series. Please refer to the original article for a comprehensive overview of the architecture.
Prerequisite: Before reading this final part, review Part 7: Load Testing & Performance Tuning.
Part 8: Zero-Downtime Map Updates & Multi-Region Kubernetes Executive Summary & Quick Answer: Deploying stateful routing engines to Kubernetes without downtime requires decoupling map graph compilation into offline jobs, hydrating Pod cache volumes via initContainers, and executing atomic Blue-Green traffic cuts via Argo Rollouts to preserve Redis semantic cache consistency.
...
Answer-First: Production load testing for geospatial microservices requires realistic traffic simulation with k6/Vegeta to identify latency spikes and connection pool bottlenecks.
Pillar Architecture Guide: This article is part of the GitOps at Scale: Kubernetes & ArgoCD for Microservices series. Please refer to the original article for a comprehensive overview of the architecture.
Prerequisite: Before starting load testing, review Part 6: Location Clustering & Semantic Caching.
Part 7: Load Testing and Performance Tuning for Production Executive Summary & Quick Answer: Load testing a high-scale routing architecture requires avoiding Coordinated Omission by using K6 open-arrival-rate models (executor: 'constant-arrival-rate'), tuning the Linux kernel TCP stack (sysctl net.core.somaxconn=65535), and profiling Go GC garbage collections using pprof.
...
Answer-First: Redis semantic caching for routing queries utilizes geo-hash indexing and embedding similarity vectors to serve frequent route lookups with sub-5ms latency.
Pillar Architecture Guide: This article is part of the GitOps at Scale: Kubernetes & ArgoCD for Microservices series. Please refer to the original article for a comprehensive overview of the architecture.
Prerequisite: Before reading this part, review Part 5: Route Visualization UI.
Part 6: Location Clustering with Uber H3 & Redis Semantic Caching Executive Summary & Quick Answer: Semantic caching transforms continuous floating-point GPS coordinates into discrete Uber H3 hexagonal keys (Resolution 8/9), increasing cache hit rates from 0% to over 80%. Combining H3 spatial keys with Redis MGET pipelines and XFetch early recomputation prevents cache stampedes and lowers matrix latency to <2ms.
...
Answer-First: High-density geospatial rendering (100,000+ telemetry vectors) requires offloading coordinate math from the browser DOM to WebGL GPU buffers via Deck.gl and Mapbox overlays. Using Deck.gl’s DataFilterExtension updates GPU uniforms in 60 FPS requestAnimationFrame loops without mutating JavaScript heap allocations.
Pillar Architecture Guide: This article is part of the GitOps at Scale: Kubernetes & ArgoCD for Microservices series. Please refer to the original article for a comprehensive overview of the architecture.
...
Answer-First: High-throughput geospatial microservices in Go leverage H3 spatial indexes, concurrent goroutines, and Protobuf gRPC APIs for real-time ETA calculation.
Pillar Architecture Guide: This article is part of the GitOps at Scale: Kubernetes & ArgoCD for Microservices series. Please refer to the original article for a comprehensive overview of the architecture.
Prerequisite: Before reading this part, review Part 3: Spatial Indexing.
Part 4: Golang API & Microservices Integration (Kratos & Dapr) Executive Summary & Quick Answer: Integrating a high-concurrency Golang API Gateway with a downstream Java routing engine requires robust defense-in-depth patterns: golang.org/x/sync/singleflight for request deduplication, sony/gobreaker circuit breakers for fail-fast isolation, and flattened 1D arrays for Protobuf distance matrix serialization to prevent Go GC pauses.
...
Answer-First: Spatial indexing serves as a high-performance pre-filtering layer that prevents heavy routing engines from collapsing under load. By using Uber H3 hexagonal cells and Redis GEO to narrow down 10,000 active drivers to the 50 closest candidates in RAM (<2ms), systems reduce routing engine CPU overhead by up to 95%.
Prerequisite: Before reading this part, review Part 2: Zero to Hero Environment Setup.
Part 3: Spatial Indexing — Uber H3, PostGIS & Redis GEO Executive Summary & Quick Answer: Spatial indexing serves as a high-performance pre-filtering layer that prevents heavy routing engines from collapsing under load. By using Uber H3 hexagonal cells and Redis GEO to narrow down 10,000 active drivers to the 50 closest candidates in RAM (<2ms), systems reduce routing engine CPU overhead by up to 95%.
...
Prerequisite: Before starting this part, review Part 1: Core Routing Algorithms Visualized.
Part 2: Zero to Hero Environment Setup (Docker, OSM, Golang) Executive Summary & Quick Answer: Setting up a production-grade routing environment requires extracting OpenStreetMap .osm.pbf map data via Osmium tools, provisioning GraphHopper Java containers with explicit JVM heap allocations (-Xmx6g), and connecting a Golang API client with exponential backoff health checks.
Key Takeaways:
Map Extraction: Bounding-box cropping with osmium extract reduces raw .osm.pbf file size by 90%, speeding up graph compilation. Container Tuning: Allocate sufficient JVM heap (JAVA_OPTS=-Xmx6g) to prevent Out-Of-Memory (OOM) failures during Contraction Hierarchies shortcut generation. Client Resiliency: Golang HTTP clients must use connection pooling (MaxIdleConnsPerHost: 100) to sustain high matrix throughput. What You’ll Learn That AI Won’t Tell You:
...
Prerequisite: This part builds on the concepts introduced in the Executive Summary.
Part 1: Core Routing Algorithms — A* & Dijkstra Visualized Executive Summary & Quick Answer: A* pathfinding uses Euclidean heuristics to accelerate 1-to-1 point routing, whereas Single-Source Dijkstra is mathematically superior for 1-to-N distance matrix calculations because it builds a single shortest-path search tree to all reachable destinations in one pass.
Key Takeaways:
Matrix Efficiency: Dijkstra expands radial wavefronts in a single pass, computing 1-to-N driver matrices 10x faster than running N independent A* searches. Turn Restrictions: Edge-based graph representation models turn penalties (e.g. prohibited U-turns) by representing turns as edges between directed road segments. Shortcut Hierarchies: Contraction Hierarchies contract local nodes offline, reducing real-time search space by orders of magnitude. What You’ll Learn That AI Won’t Tell You:
...