WIREFRAME.md

solverforge-deliveries WIREFRAME

This file is the architectural map for the deliveries example.

README.md explains how to run and use the app. This document explains how the pieces fit together and where each responsibility lives.

Documentation Roles

• README.md Quick start, dependency shape, route list, and user-facing orientation.
• WIREFRAME.md Architecture, execution flow, and file-map walkthrough.
• AGENTS.md Repo-specific contribution, validation, and documentation rules.
• Makefile Local development, validation, and Space/Docker command surface.
• Dockerfile Hugging Face Docker Space image definition.
• docs/screenshot.png Current browser screenshot embedded by the README.

What This Repo Is Teaching

This repo is a complete solverforge-deliveries 1.0.1 list-variable SolverForge app for delivery routing.

It shows how to combine:

• a Plan solution with a list planning variable
• route-specific score rules
• SolverForge CVRP construction and local-search hooks
• solverforge-maps road-network preparation and route geometry
• retained jobs with snapshots, analysis, cancel, pause, resume, and SSE
• a browser plan viewer built on stock solverforge-ui assets

SolverForge Concepts In Plain Language

• Delivery Input stop data. The solver assigns delivery IDs into vehicle routes.
• Vehicle Planning entity. Each vehicle owns one ordered delivery_order list.
• Plan Planning solution. It holds deliveries, vehicles, score, routing mode, view state, and prepared routing data.
• hard score Missing assignments, capacity overage, late delivery seconds, and unreachable route legs.
• soft score Total travel seconds.
• retained job A solve that lives in memory so the UI can stream events, fetch snapshots, pause/resume, cancel, analyze, and delete terminal jobs.

Runtime Flow

1. The browser loads static/index.html.
2. static/app/main.mjs loads static/sf-config.json.
3. The app fetches /demo-data/PHILADELPHIA.
4. PlanDto::from_plan() serializes a refreshed transport plan with preview state.
5. The browser normalizes the plan, renders summary cards, tables, timelines, and a map.
6. When the user clicks Solve, the browser sends the current plan to POST /jobs.
7. src/api/routes.rs deserializes the PlanDto, rebuilds a Plan, and calls prepare_plan().
8. prepare_plan() builds straight-line or road-network matrices and attaches PreparedVehicleRouting to each vehicle.
9. SolverService starts a retained solve through SolverManager<Plan>.
10. Solver events are converted by src/solver/service/runtime_payload.rs into UI-facing JSON.
11. The browser consumes /jobs/{id}/events and fetches snapshots, analysis, and route geometry for exact snapshot revisions.
12. Road-network route geometry follows the solverforge-maps graph route, projects each leg endpoint onto the nearest road segment, and stitches the exact depot or delivery coordinate back in before encoding so each displayed leg reaches the visible markers.

File Map

.
├── Cargo.toml
│   Rust 1.95 crate metadata for app version 1.0.1 and registry dependency
│   requests.
├── solver.toml
│   Embedded search policy for construction heuristics and local search.
├── solverforge.app.toml
│   App metadata, demo IDs, model facts/entities, registry dependency sources,
│   and the `solverforge 0.13.1` runtime target.
├── Makefile
│   Hospital-style local build, validation, and Space/Docker commands.
├── Dockerfile
│   Multi-stage Rust 1.95 Docker image for Hugging Face Spaces.
├── .dockerignore
│   Keeps build artifacts, git metadata, route cache, and Playwright output out
│   of the Docker context.
├── README.md
│   Run guide, dependency shape, API list, and learning path.
├── AGENTS.md
│   Repo-specific rules for future edits.
├── WIREFRAME.md
│   This architectural walkthrough.
├── docs/screenshot.png
│   Current browser screenshot used by the README.
├── src/
│   ├── domain/
│   │   `planning_model!` manifest, `Plan`, entities, facts, preview structs,
│   │   and route metrics.
│   ├── constraints/
│   │   Assignment, capacity, time-window, and travel-time score rules.
│   ├── data/
│   │   Deterministic city seed data and generator entrypoints.
│   ├── solver/
│   │   Retained-job service and runtime event payload formatting.
│   └── api/
│       Axum routes, DTOs, and SSE endpoint.
├── static/
│   ├── index.html
│   ├── sf-config.json
│   ├── generated/ui-model.json
│   └── app/
│       Browser controller, plan models, and UI renderers.
└── tests/
    ├── api_contract.rs
    │   Single integration-test crate composed from `tests/api_contract/*.rs`.
    ├── api_contract/
    │   Catalog, job, lifecycle, SSE, and live-road modules.
    ├── support/
    │   Shared integration-test helpers used by that single crate.
    ├── e2e/
    │   Playwright browser tests for the served app.
    └── frontend_models.test.mjs
        Frontend model tests.

Domain And Route Metrics

src/domain/plan.rs stays small and macro-facing. It owns the Plan struct, normalization, list shadow refresh, transport refresh, and the VrpSolution implementation.

Route-specific behavior lives under src/domain/route_metrics/:

• preparation.rs Builds matrices and per-vehicle prepared routing data.
• cvrp_hooks.rs Supplies Clarke-Wright, k-opt, load, capacity, and route replacement hooks.
• metrics.rs Computes per-vehicle route metrics.
• scoring.rs Builds preview DTOs and aggregate hard/soft score components.
• routes.rs Builds straight-line or road-network route geometry snapshots, including edge-projected visual endpoints for road legs.
• insertions.rs Ranks candidate insertion positions for one delivery.
• types.rs Shared route metrics, snapshots, candidates, and routing trait types.

This split keeps the public domain API stable while avoiding oversized files.

Demo Data

src/data/data_seed/entrypoints.rs exposes three demo IDs:

• PHILADELPHIA
• HARTFORD
• FIRENZE

Each city has a small module with separate depot and grouped visit files. The generator is deterministic. Every demo has ten vehicle depots, enough scaled deliveries for those vehicles, reachable road-network coordinates, and enough aggregate capacity before route ordering.

API And Retained Runtime

The REST API handles job control and snapshot reads:

• /jobs creates a retained solver job.
• /jobs/{id} and /jobs/{id}/status expose summary state.
• /jobs/{id}/snapshot returns an exact or latest snapshot.
• /jobs/{id}/analysis runs constraint analysis for a snapshot.
• /jobs/{id}/routes returns route geometry for a snapshot.
• /jobs/{id}/events streams typed lifecycle events.

The insertion endpoint, /recommendations/delivery-insertions, is app-specific. It prepares the submitted plan, removes the requested delivery from any existing route, evaluates candidate insert positions, and returns preview plans.

Frontend Layout

static/app/main.mjs is the controller. It owns current plan state, retained job state, route identity tracking, and event handlers.

Supporting modules are split by responsibility:

• static/app/models/core.mjs Clone and normalize incoming plans.
• static/app/models/preview.mjs Draft straight-line preview scoring.
• static/app/models/timeline.mjs Vehicle and delivery rail models.
• static/app/models/formatters.mjs Labels, icons, tones, clocks, and durations.
• static/app/ui/layout.mjs Page shell and stock SolverForge UI component composition.
• static/app/ui/overview.mjs Summary, route list, vehicle-id keyed route highlighting, map, and timeline rendering. The tutorial uses ten distinct map colors for its ten fixed vehicles.
• static/app/ui/data-tables.mjs Read-only vehicle and delivery tables with delivery insertion recommendations.
• static/app/ui/modals.mjs Analysis and insertion recommendation bodies.
• static/app/ui/api-guide.mjs Visible API guide content.
• static/app/ui/lifecycle.mjs Dataset markers and route-identity helpers.

Validation Surfaces

Use the Makefile as the repo-local workflow:

• make fmt-check
• make clippy
• make build-release
• make test
• make test-e2e
• make space-build
• make test-live-road
• make ci-local
• make pre-release

make ci-local includes the Docker image build used by the Hugging Face Space. The Playwright command uses the publication bundle's root Node dev dependency; runtime UI assets are served from the declared solverforge-ui Cargo crate.

The file-size rule is part of the architecture: keep files below 300 lines and split by responsibility before they become broad catch-all modules.