← Back to the visualizer

Inventory Manager — Buckets & Grains

How HME's warehouse stock is identified and counted · DFSV explainer · first draft

What is a bucket?

A bucket is one group of identical stock the warehouse keeps a single running count for. Its identity — the grain — is not one column but a combination of columns: the same part, in the same place, is one bucket; change any part of that identity and it's a different bucket.

Grain (bucket)
The level of detail one stock group represents — the columns that, combined, form its identity (a natural composite key). "One aggregated grouping of transactions."
Net (running balance)
A bucket's on-hand quantity = SUM(Quantity) of all its rows. It is derived, never stored — there's no separate balance to keep in sync.
The ledger (transaction log)
Every stock movement is an append-only row (inv.MasterTable). Nothing is edited or deleted; the count changes by adding more rows.

So there is no "quantity on hand" field anywhere. On-hand is always computed by gathering a bucket's transaction rows and summing their signed quantities. That's the whole model in one sentence — the rest of this page is what makes up a bucket's identity, and why getting that identity right matters.

Anatomy of a bucket — the grain key

The base identity is four levels, most-broad to most-specific. Combined, they are the bucket's natural key. A part on the top shelf of Warehouse A at Fort McKay is a different bucket from the same part out in Yard B, or in a different sub-location — even though it's the same part number.

The bucket — five columns read as one combined identity
Site
Fort McKay
Part No
2755110
Location
Warehouse A
Sub-location
Top Shelf
ItemCode
ITM For HME 5th level

every ledger row carrying these five values lands here — and only here

+10Add from PO −4Issued +2Return
SUM(Quantity)
8
On-hand = net (running balance)

The five identity columns sit side by side like a table row — the four base columns (blue) plus the optional ItemCode (amber). Ledger movements that carry all five values collect inside the bucket, and their signed quantities sum to on-hand.

Why identity matters (BR-NET-1). A transaction only counts toward a bucket if it carries the same identity values. Put a movement on the wrong location — or with a missing/wrong ItemCode — and it lands in a different bucket. The two never net: one stays overstated while the other drifts. Most "the count is wrong" issues trace back to a row landing in the wrong bucket.

The optional 5th level — same shelf, different bucket

Most of the company (~80% of inventory, ~90% of sites) runs on the 4-level base grain above and never uses ItemCode. Where ITM undercarriage stock lives (~20% of inventory), a 5th level — ItemCode — splits a single physical part-and-place into separate buckets by line of business:

Site
Fort McKay
Part No
2755110
Location
Warehouse A
Sub-location
Top Shelf
same part, same shelf — ItemCode splits it into separate buckets
ItemCode · ITM For HME
ITM parts installed into HME's own machines
+10Add from PO −4Issued +2Return
net (on-hand)8
ItemCode · ITM Retail
ITM parts resold to customers (retail)
+6Add from PO −4Issued
net (on-hand)2

Same shelf, two buckets — the retail stock and the HME-machine stock count separately — each keeps its own on-hand.

Domain is closed: only these codes are valid — any other value would wrongly fragment the grain into spurious buckets. (Stock outside ITM simply carries no code and stays on the 4-level base grain; those rows are left out of this page's examples for simplicity.)

Try it — watch 20 transactions collapse into buckets

Here are 20 sample ledger rows — one part, two sites — sorted by site. Switch each level on, left to right: a true GROUP BY builds up, with Site leading the key throughout. Watch the rows consolidate while every column keeps showing data: a column not yet grouped shows its real value when the pile has just one, or rolls up ("2 locations") until its level switches on and resolves it. Then flip the data-issue checkboxes: every identity column except ItemCode can carry an imported defect — misspelled names, a stray dash, a missing space — and each one creates phantom buckets that its fix folds away. Green text means the value checks out against the picklists and master parts; amber flags what doesn't. The app's forms use picklists, so hand-entered Sites and Locations can't be wrong — but imports can bypass the picklists, which is exactly how bad values sneak into "safe" columns.

Data issues

Takeaway. "How much of part 2755110 do we have?" has no single answer until you pick a grain — and if the data carries a typo'd description or a stray dash in a part number, even the right grain gives a wrong answer: phantom buckets that never net together. The bucket is the question, and clean identities are what make it answerable.

Drill down — watch on-hand break apart

The table above starts from raw transactions and groups up. This one runs the other way: it starts from the simplest possible answer — part number and on-hand — and drills down. Every click adds a column, and the on-hand number breaks apart into smaller, truer piles. Same 20 movements as above — and the same data-issue checkboxes.

Data issues

Time to productivity — what preventing each issue costs

The Data issues checkboxes make defects appear in the tables; this tab shows what it takes to make them impossible — written the way a requirements document starts. Each card lists the rules that guarantee clean data, the extra UI steps they demand, and a first-pass time cost. An easy-to-use system means seconds to transact — a short time to productivity — while a powerful, locked-down system asks for those seconds back up front… and one rule below can stop work dead, not just slow it down. The point isn't that one side is right: it's to decide, with eyes open, whether the team has the time — and the information — to feed the powerful version. These lists will grow; treat every number as a draft.

Data issues
Configuring for:

Each site keeps its own selections — what Fort Hills enforces, Fort McKay may decide it hasn't the manpower for. Save writes both.

⛔ The hard stop, illustrated. A storeman receives a brand-new part. Locked-down mode says: add it to Master Parts (two minutes — fine) and give it a cost. But there's no invoice line and the vendor can't be reached. This transaction doesn't take longer — it doesn't happen. The part sits unreceivable until someone supplies a cost. That is the real price of "the part must have a cost": a business decision wearing a technical jacket. Decide it deliberately.

Neither end is "right": speed today creates cleanup tomorrow, while validation up front costs minutes per new part but makes every bucket trustworthy. The dial can be set per column — that conversation is the roadmap.

For IT — the saved configuration (JSON)
Nothing saved yet — tick requirements per site and hit Save configuration.

The transaction ledger, in depth

Next draft: the movement types (Issued / Return / Transfer / Adjust / Add from PO), the sign convention, and how a two-row transfer moves stock between sites — all as append-only rows on the ledger.

Master parts ↔ the ledger

Next draft: how MasterPartsTable (one authoritative name + description per part) relates to the ledger by a normalized part number, and the match / orphan indicator that keeps the model permissive without forcing every site to register parts up front.

Buckets & grains — concepts from inventory-manager-3.0 BUSINESS_RULES.md (BR-GRAIN-*, BR-NET-1, BR-MODEL-2/3/4, BR-ITEM-*). Sample data and times are illustrative drafts.