Skip to content
Honeywick Consulting

hubObject

A hub is a preferred staging point where a logistical shipment that cannot be delivered effectively in a single leg may be split. Available from Spiral 2.5. Spiral may choose to assign a delivery to a hub — it puts the hub’s id in the delivery stop’s location, loc.hid, with the hub’s address in loc.addr (see stopObject’s loc), telling the client the leg can be staged (split) at that location. A hub attracts a discount for its use, and has a location.

A hub is a top-level input entity, authored and mutated exactly like a surgeZone — a { "add": { "hub": … } } command, keyed by numeric id, committed before scheduling so it streams to the client and can be edited live.

{
"id": <integer>,
"at": <location>,
"discount": <real>,
"domain": <string> | null,
"active": <bool> | null,
"seqno": <integer> | null,
"color": <string> | null,
"name": <string> | null,
"address": <string> | null,
"addr": object | null,
"ext": <object> | null,
}
id integer
Unique identifier for the hub — the value Spiral stamps onto a delivery’s stop to mark a leg that may be split (staged) here.
at location
The hub’s staging location. Only the position is sent to Spiral.
discount real
The cost discount a shipment attracts for staging through this hub. Sent to Spiral.
domain string
The domain the hub applies to — a domain name declared by stop / resource types, as with a surgeZone. Absent / null = the hub applies to ALL domains. Sent to Spiral.
active bool
Switches the hub on / off within Spiral.
seqno integer
Helix-only — optimistic-lock sequence number (a missing value reads as 0, so older records heal on first edit).
color string
Helix-only — a colour-palette name or CSS value used to render the hub marker on the map; never sent to Spiral.
name string
Helix-only LEGACY fallback — a flat display name for clients not using addr. The preferred source is the addr object: the domain declares which addr field is the name via the app-level helix config `hub: { nameField: "…" }`; unconfigured, the display defaults to the stringified addr.
address string
Helix-only — a human-readable form of the hub’s location, shown in the UI; never sent to Spiral.
addr object
The hub's ADDRESS object — the loc within the helix objects, whose schema is PROPRIETARY TO THE CLIENT. Sent to Spiral WHOLE from 2.5.2 (it was Helix-only before): Spiral carries it into the staged stop's loc envelope {at, hid, addr} so a client reading the output stream has the address without a second lookup. Nothing reads its fields directly — display goes through the app-level helix.addr doors (addr.name(), addr.addr(), addr.at(), addr.tel()); the default structure is {name, line1, line2, area, postcode, at, tel} and a client that restructures it (the AA pack authors {name, lines, area, code}) overrides the doors in its extension.
ext object
Helix-only — client extension metadata; never sent to Spiral.

Helix-only fields

Section titled “Helix-only fields”

Spiral receives the hub’s position (at), its discount, domain, active flag and — from 2.5.2 — its addr. Every other key — name, address, color, ext, or any additional field a client authors — is Helix-only display / operational metadata: stored, streamed to the dispatch UI, and never forwarded to Spiral.

The hub is the one entity whose forwarding is an allow-list rather than a deny-list, which is what lets it carry arbitrary client metadata without Spiral seeing a key it does not know.

Domain-carried hubs

Section titled “Domain-carried hubs”

A domain file may seed hubs directly ({"add":{"hub":…}} lines): Helix stores them into the live world on every Spiral (re)launch, so run-file loads and restarts keep them, while Spiral receives them through its own include of the same file. From 2.5.2 the address is authored at the record’s root, beside at and discount, because Spiral’s hub parser now takes it:

{"add":{"hub":{"id":1,"at":[52.387,-0.2566],"discount":10.0,
               "addr":{"name":"Depot Alconbury","lines":"Sawfield Business Center",
                       "area":"Alconbury Hill","code":"PE28 4JL"}}}}

A record’s optional helix wrapper still holds whatever a given Spiral will not parse — the Helix-only name, and any client-added field — and Helix lifts every wrapped field onto the stored record’s root, so the UI sees them as first-class either way.

Editing

Section titled “Editing”

Hubs appear in the dispatch panel under the Desks / Surge Zones / Hubs toggle (click the panel title to cycle). Each hub is a point marker on the map; adding one, double-clicking a hub row or its marker opens the hub editor, where its location, discount, name, address, colour and active flag are set.

Section titled “Related”