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

```text
.
├── 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.