House-move inventory: Status, going? and a history - Part 11
~8 min read
A box has a status: packing, sealed, in transit, arrived, unpacked. That was in the very first design. What I hadn't predicted was how much a move is also a long series of decisions about things that aren't packed at all. This post is about the two extra fields that grew onto boxes, the history that records them, and a rule about dependent fields that I'd defend in a code review.
Two independent axes
Status is the physical lifecycle: packing → sealed → in_transit → arrived → unpacked. It answers "where is this box?".
Going? (decision, Phase 3.27) answers a different question: "is this box coming with us at all?". Its values are definite, maybe and no, defaulting to definite.
They are deliberately independent. A box can be sealed and fully packed while still maybe - the decision on whether it goes might wait on the size of the lorry. If I'd folded "maybe" into the status list I'd have needed a status for every combination. Two small enums beat one big one.
The UI gives each a pill: status with its own colours, and Going? as a traffic light - green definite, amber maybe, red no (DecisionPill). The box list shows both as columns and both are filters.
A field that only exists sometimes
When a box is not going, the next question is why. Is it being sold, or thrown away ("tipped")? Phase 3.36 added sub_status - selling or tipping.
The design question was where to put it. A flat Box.reason field would be meaningful for a "no" box and nonsense otherwise, and nothing would stop you setting it on a box that's definitely coming. The rules I settled on:
sub_statusis nullable, and optional even when the decision is "no". A box can sit atnowith the reason still unset - the UI calls that "Undecided" - because forcing a choice at the moment you decide not to take something is annoying.set_box_sub_statusrejects with a 422 unlessdecisionis currentlyno.- And in the other direction,
set_box_decisionclearssub_statusback to null the instant the decision changes to anything else. In the same write, with no separate event.
That last point is the one worth stealing. The invariant "a reason exists only while the answer is no" isn't enforced by a check somewhere that might get skipped; it's maintained by the only function that can break it. The history already records the decision_changed event, which explains the clearing, so there's no second entry to confuse things.
The same rule shows up in cloning. clone_box copies the source box's decision (a clone is "more of the same kind of box", so the call usually still applies) but resets status to packing.
History, append-only
I added the box history early (Phase 3.16) because "who moved the lamp box to the garage, and when?" is a surprisingly common question when two people pack.
box_events is an append-only table: nothing is updated or deleted. Each row has the box, a timestamp and a kind - created, cloned, renamed, moved, status_changed, and later decision_changed and sub_status_changed - plus a detail string. The migration that added it back-filled a created entry for every existing box, so old boxes aren't history-less.
The service logs events as a side effect of the operation: renaming a box writes the rename and the event together. The box page shows a History timeline, auto-refreshing when the box changes, with a line per event. The clock injection from post 2 is what makes the ordering testable.
Adding a new kind later costs two things: a new value, and a line in the timeline renderer. Phases 3.27 and 3.36 each did exactly that.
Rolling it up
Once boxes have this much structure, the questions get more interesting, and the answers come from aggregation in the core:
- Move by room (Phase 3.17):
summary_by_room()returns box count, lines, items and value per room, with a totals footer and the fixed-rate note. - Move by box: the original whole-move table.
- Missing French (post 8): a top-level view of what still needs translating.
Aggregations are the exact thing that tends to creep into the transport layer ("I'll just add these up in the route"), and the architecture rule - no aggregation outside the core - means each of them is a method with a test instead of a loop in a handler.
Sorting is just UI
A small coda: the box list got sortable columns on 27 October (BoxList.tsx). It's client-side - a useMemo over the fetched list, with a click-to-toggle direction. There's one rule I like: empty values always sort last, whichever direction you're sorting, so clicking "name" doesn't bury your named boxes under a wall of blanks. Not everything needs to touch the core; sorting a list that's already on the page is presentation.
Next: all of this feeds the filters on the room export - and the last feature I shipped, exporting every room at once.
Previous: ← Built, then deleted: authentication · Next: Filters, and exporting everything →
