WIREFRAME.md

solverforge-fsr WIREFRAME

This file is the architectural map for the field-service routing 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, API 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.

What This Repo Is Teaching

This repo is a complete solverforge-fsr list-variable SolverForge app for field-service routing in Bergamo.

It shows how to combine:

• a FieldServicePlan solution with a list planning variable
• route-level hard and soft score rules
• precomputed travel-leg facts and solverforge-maps road-network geometry
• retained jobs with snapshots, analysis, cancel, pause, resume, and SSE
• a browser map workspace built on stock solverforge-ui assets

SolverForge Concepts In Plain Language

• Location Input place data. Depots and customer sites are indexed so routes can refer to them cheaply.
• ServiceVisit Input job data. The solver places visit indexes into technician routes.
• TravelLeg Input travel data. Each leg records duration, distance, and whether the road graph can connect the two locations.
• TechnicianRoute Planning entity. Each technician owns one ordered visits list.
• FieldServicePlan Planning solution. It holds facts, route entities, and the current score.
• hard score Missing visits, duplicate visits, invalid visit indexes, unreachable legs, missing skills or parts, late visits, and route overtime.
• soft score Travel cost, workload balance, territory fit, and priority slack.
• 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.js loads static/sf-config.json and static/generated/ui-model.json.
3. The app fetches /demo-data/STANDARD.
4. The backend returns a FieldServicePlan with seed travel legs.
5. The browser renders route cards, tables, timeline, map shell, and the visible REST API guide.
6. When the user clicks Solve, the browser posts the current plan to POST /jobs.
7. src/api/routes.rs deserializes the PlanDto; domain deserialization and FieldServicePlan::normalize() restore transient service-visit indexes and route shadow fields before routing preparation.
8. prepare_routing() loads or fetches the Bergamo road network, computes the full travel matrix, and replaces seed legs with road-network legs.
9. SolverService starts a retained solve through SolverManager<FieldServicePlan>.
10. Solver events are converted by src/solver/event_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. src/api/route_geometry.rs builds map segments, preserving non-routed statuses so one unreachable leg does not hide the rest of a route.

File Map

.
├── Cargo.toml
│   Rust 1.95 crate metadata for the app package and registry dependency
│   requests.
├── solver.toml
│   Embedded search policy for list construction and local search.
├── solverforge.app.toml
│   App metadata, demo IDs, model facts/entities, registry dependency sources,
│   and the `solverforge 0.19.3` runtime target.
├── Makefile
│   Local build, validation, and Space/Docker commands.
├── Dockerfile
│   Multi-stage Rust 1.95 Docker image for Hugging Face Spaces.
├── 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, facts, route entity, shadows, and solution.
│   ├── constraints/
│   │   Mostly stock SolverForge streams plus the custom duplicate-assignment
│   │   counter in `assigned_visits.rs`.
│   ├── data/
│   │   Deterministic Bergamo seeds, demo entrypoints, and OSM matrix loading.
│   ├── solver/
│   │   Retained-job service and runtime event payload formatting.
│   └── api/
│       Axum routes, DTOs, route geometry, and SSE endpoint.
└── static/
    ├── index.html
    ├── sf-config.json
    ├── generated/ui-model.json
    └── app*.js
        Browser controller, map rendering, route state, layout, and tables.

Domain And Route Metrics

src/domain/field_service_plan.rs owns the public solution shape. It keeps the SolverForge model explicit: facts are read-only inputs, while TechnicianRoute.visits is the one mutable list variable. Its custom deserializer and normalize() method rebuild skipped transient visit indexes and route shadow values after JSON round trips, direct deserialization, and seed travel-matrix replacement.

Route-specific scoring math lives in src/domain/route_metrics.rs. That module walks a route from depot to visits to depot, advances a service clock, and records reusable counters as TechnicianRoute shadow values. The constraint files then use stock SolverForge ConstraintFactory streams over those shadow fields. The assignment module uses stock streams for missing visits and invalid route visit indexes; duplicate assignments use a small custom IncrementalConstraint so /jobs/{id}/analysis reports matches only for visit indexes assigned more than once while scoring each extra valid assignment.

src/api/route_geometry.rs is separate because map drawing has a different job from scoring. Scoring consumes matrix facts already on the plan; geometry loads the road graph to draw visible polylines for a retained snapshot.

Demo Data

src/data/data_seed.rs exposes one demo ID:

• STANDARD

The generator is deterministic. It builds two depots, 24 customer locations, 48 visits, six technicians, and seed self-leg travel facts. Full road-network travel facts are prepared when a job is created.

API And Retained Runtime

The REST API handles discovery, job control, snapshots, and route geometry:

• /health and /info expose liveness and app metadata.
• /demo-data and /demo-data/{id} expose the deterministic demo catalog.
• /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}/pause, /jobs/{id}/resume, and /jobs/{id}/cancel control a live job.
• DELETE /jobs/{id} removes a terminal retained job.
• /jobs/{id}/events streams typed lifecycle events.

Frontend Layout

static/app.js is the controller. It owns current plan state, retained job state, route focus, event handlers, and analysis modal wiring.

Supporting modules split the UI by responsibility:

• static/app-dataset.js Demo catalog and plan loading.
• static/app-layout.js Page shell and stock SolverForge UI component composition.
• static/app-route-state.js Snapshot identity and route geometry cache coordination.
• static/app-render*.js Summary cards, route cards, maps, timeline, tables, and API guide.
• static/app-utils.js Plan cloning, labels, formatting, and color 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 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.