README.md

---
title: SolverForge Deliveries
emoji: 🚚
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: SolverForge delivery-route optimization example
---

# SolverForge Deliveries

`solverforge-deliveries` is a SolverForge vehicle-routing example with retained
jobs, route geometry, insertion recommendations, and a browser plan viewer.

It answers one concrete question:

"Given depots, vehicles, delivery stops, capacities, and time windows, which
vehicle should visit each delivery and in what order?"

## Documentation Map

- `README.md`
  Quick start, concepts, API surface, and the shortest learning path.
- `WIREFRAME.md`
  Architecture and request/data flow across backend, runtime, maps, and UI.
- `AGENTS.md`
  Repo-specific contribution, validation, and documentation rules.
- `Makefile`
  The supported local command surface for development, validation, and
  Docker-based Hugging Face Space preparation.
- `Dockerfile`
  The Docker Space image build, using Rust 1.95 and published crates.io
  dependencies.

## Current Dependency Shape

The app package version is `1.0.1`; the release binary is
`solverforge_deliveries`.

This repo requires Rust `1.95` and is configured against published crates.io
dependencies. Direct dependency declarations currently pin these published
versions:

- `solverforge` `0.11.1`
- `solverforge-ui` `0.6.5`
- `solverforge-maps` `2.1.3`
- `axum` `0.8.9`
- `tokio` `1.52.1`
- `tokio-stream` `0.1.18`
- `tower-http` `0.6.8`
- `tower` `0.5.3`
- `serde` `1.0.228`
- `serde_json` `1.0.149`
- `rand` `0.10.1`
- `uuid` `1.23.1`
- `parking_lot` `0.12.5`
- `http-body-util` `0.1.3`

The app metadata in `solverforge.app.toml` mirrors that published dependency
shape and records `solverforge-cli` `2.0.1` as the current scaffold metadata
line.

## What SolverForge Is Doing Here

- `Delivery` is a problem fact: a stop the solver must place in a route.
- `Vehicle` is a planning entity: each vehicle owns one mutable route.
- `Vehicle.delivery_order` is the list planning variable.
- `Plan` is the planning solution, matching the current `solverforge-cli`
  default solution name and `src/domain/plan.rs` file shape.
- Constraints score assignment coverage, capacity, time-window violations, and
  total travel time.
- `solver.toml` selects list construction heuristics and local-search moves.
  It matches the hospital example's stop policy: 30 seconds total, or 5 seconds
  without improvement.

The app ships three city datasets:

- `PHILADELPHIA` (default)
- `HARTFORD`
- `FIRENZE`

Each dataset has ten vehicles: 82 Philadelphia deliveries, 50 Hartford
deliveries, and 80 Firenze deliveries. Philadelphia is the default road-network
baseline, and all current seed data has enough aggregate vehicle capacity and
reachable street-front coordinates for the configured delivery stops.

## Quick Start

```sh
make run-release
```

Then open `http://localhost:7860`.

To inspect the command surface:

```sh
make help
```

## Validation

Standard validation:

```sh
make test
```

Full local validation:

```sh
make ci-local
```

Space image validation:

```sh
make space-build
```

Live road-network smoke:

```sh
make test-live-road
```

`make test` includes Rust tests, browserless frontend tests, and Playwright
browser tests. The Playwright defaults point at the sibling
`../solverforge-ui` checkout's Node modules; set `PLAYWRIGHT` and
`PLAYWRIGHT_NODE_PATH` when using a different local installation.

`make ci-local` adds the Docker image build used by the Hugging Face Space.
`make pre-release` runs `make ci-local` and then the live road-network smoke
test. The live road test may touch the local `.osm_cache/` through
`solverforge-maps`; that cache is ignored by git and by Docker builds.

## Hugging Face Space Deployment

This repo is Docker-Space ready. The Space reads the README front matter,
builds `Dockerfile`, and expects the app to bind `PORT=7860`.

Local Space-equivalent commands:

```sh
make space-build
make space-run
```

## Read The Code In This Order

1. `src/domain/mod.rs`
   The `planning_model!` manifest and public domain exports.
2. `src/domain/plan.rs`
   The `Plan` solution and list-variable shadow-refresh wiring.
3. `src/domain/delivery.rs` and `src/domain/vehicle.rs`
   The fact and planning-entity models.
4. `src/domain/route_metrics/`
   Route preparation, CVRP hooks, scoring preview, route geometry, and insertion
   ranking.
5. `src/constraints/mod.rs`
   The constraint-set assembly point.
6. `src/constraints/*.rs`
   One scoring rule per file.
7. `src/data/data_seed/entrypoints.rs`
   Public demo-data IDs and generator dispatch.
8. `src/data/data_seed/{philadelphia,hartford,firenze}/`
   City depots and delivery coordinates.
9. `src/solver/service.rs`
   Retained-job orchestration over `SolverManager<Plan>`.
10. `src/api/routes.rs`, `src/api/dto.rs`, and `src/api/sse.rs`
    REST, DTO, and event-stream contracts.
11. `static/app/main.mjs`
    Browser controller.
12. `static/app/models/` and `static/app/ui/`
    Frontend plan normalization, preview modeling, layout, maps, tables, and
    modals.

## Project Shape

- `src/domain/`
  Planning model, domain types, route metrics, and test-only model checks.
- `src/constraints/`
  Incremental SolverForge scoring rules.
- `src/data/`
  Deterministic city demo-data generator.
- `src/solver/`
  Retained-job facade and runtime event payload formatting.
- `src/api/`
  Axum routes, DTOs, and SSE endpoint.
- `static/app/`
  Browser modules built on stock `solverforge-ui` assets.
- `Dockerfile`
  Multi-stage Rust 1.95 Alpine build for the Hugging Face Docker Space.
- `tests/api_contract/`
  Integration tests for catalog, jobs, lifecycle, SSE, and road-network smoke.
- `tests/frontend_models.test.mjs`
  Browserless frontend model tests.
- `tests/e2e/`
  Playwright tests for the served browser app, including asset loading, dataset
  switching, route highlighting, and retained solve start/stop.

## REST API

- `GET /health`
- `GET /info`
- `GET /demo-data`
- `GET /demo-data/{id}`
- `POST /jobs`
- `GET /jobs/{id}`
- `GET /jobs/{id}/status`
- `GET /jobs/{id}/snapshot`
- `GET /jobs/{id}/analysis`
- `GET /jobs/{id}/routes`
- `POST /jobs/{id}/pause`
- `POST /jobs/{id}/resume`
- `POST /jobs/{id}/cancel`
- `DELETE /jobs/{id}`
- `GET /jobs/{id}/events`
- `POST /recommendations/delivery-insertions`

Lifecycle semantics:

- `pause` requests a runtime-managed pause and checkpoint.
- `resume` continues from the retained checkpoint.
- `cancel` stops a live or paused job.
- `delete` removes a terminal retained job before the next fresh solve.
- `snapshot_revision={n}` is optional for snapshots, analysis, and routes.
- SSE reconnects bootstrap from the retained runtime status/event state.

## Routing Modes

`road_network` is the default and uses `solverforge-maps` to fetch or load a
road graph for the current plan bounds. `straight_line` is available as a fast
draft/testing mode. Route geometry is returned by `/jobs/{id}/routes` and drawn
in the browser map only when it matches the active snapshot and routing mode.
Road-network geometry follows the `solverforge-maps` graph route, projects each
leg endpoint onto the nearest road segment, and then stitches the exact
depot/delivery coordinate back in so visible legs reach the markers. The route
list highlights by vehicle id, not by line color, so one selected vehicle route
is emphasized while the rest of the map geometry is dimmed without changing the
user's current map viewport.

## Solver Policy

`solver.toml` is embedded by `Plan` and is the runtime source of truth:

- `list_clarke_wright` builds delivery routes.
- `list_k_opt` improves construction output before local search.
- local search combines nearby list change/swap, reverse, k-opt, ruin, and
  limited sublist moves.
- `late_acceptance` and `accepted_count` control acceptance and retained
  candidates.
- solving stops after 30 seconds total or after 5 unimproved seconds, matching
  the hospital tutorial.

The city seeds have coherent capacity and reachable road-network coordinates so
local search can reach feasible `0hard` road-network solutions. Current seed
sizes are 82 Philadelphia deliveries, 50 Hartford deliveries, and 80 Firenze
deliveries, each with ten vehicles.