The problem
Last-mile delivery is where logistics costs concentrate and where service promises are either kept or broken. The final stretch from a local hub to a customer’s door involves the most stops, the most variability and the least room for error.
Routes, hubs and service-level commitments are tightly connected. When something goes wrong, such as a delayed vehicle or a closed road, the useful question is not only “what happened?” but “what else does this affect?”. When that knowledge is spread across separate systems and spreadsheets, answering it is slow, and by the time it is answered the promise may already be broken.
What we built
A knowledge graph that models the delivery network directly, with routes, hubs and SLAs as connected entities. Optimization and exception handling run on top of it, and the whole capability is exposed through APIs so existing systems can use it. The work covered graph modelling, API design and the optimization itself.
Why a graph
A delivery network is naturally a graph: hubs are connected by routes, routes serve areas, and deliveries carry service commitments. Relational tables can represent this, but questions that follow connections, such as which commitments depend on a particular hub, become complicated joins that are slow to write and slow to run.
A graph database stores the connections themselves. Questions that follow relationships become natural to express and fast to answer, because the database walks the connections directly rather than reconstructing them from tables.
How it works
- The graph. Neo4j stores the network. Routes, hubs and SLAs are nodes, and their relationships are edges.
- Queries. Cypher, Neo4j’s query language, expresses questions as patterns of connections. A query such as “which deliveries with an SLA due today pass through this delayed hub?” reads close to how a person would ask it.
- Optimization. Routing decisions draw on the relationships the graph makes explicit.
- Exception handling. When a delivery goes off-plan, its impact is traced through the graph, so the right action happens faster.
- APIs. FastAPI exposes the capability to the systems that need it, so the graph becomes part of existing operations rather than a separate tool.
What the results mean
The system got more deliveries there on time, shortened the routes and meant problems were sorted out faster. On-time delivery is the customer-facing measure: promises kept. Route time is the cost measure: less time on the road for the same work. Faster exception resolution is where the graph earns its place, because tracing the impact of a problem is exactly the question it was built to answer.
Where it can go wrong
- A stale graph. A model of the network is only useful if it matches the network. Changes to routes, hubs and commitments must flow into the graph promptly.
- Over-optimization. A route that is optimal on paper can be impractical for a driver. Optimization needs constraints from people who know the ground.
- Integration gaps. Insight that does not reach the dispatcher at the moment of decision changes nothing, which is why the APIs matter as much as the graph.
When this approach fits
A graph model suits operations where the important questions are about connections and knock-on effects. If the questions are mostly aggregates, such as totals and averages over time, conventional analytics may be simpler and just as effective.
Questions to ask before building one
If you are considering a system like this, these are the questions we would want answered first.
- What are the questions you cannot answer quickly today? If they are about connections and knock-on effects, a graph is likely a good fit.
- How will the graph stay current? Changes to routes, hubs and commitments need a reliable path into the model.
- Who acts on the output, and when? Insight only helps if it reaches a dispatcher at the moment of decision.
- What constraints do drivers know that the data does not? Capture them, or optimized routes will not survive contact with the road.