Shelfery Domain Concepts¶
This document describes the core conceptual entities in the Shelfery domain at a modeling level — how the domain is understood, not how it will be implemented. It intentionally stops short of defining a data schema, API shape, or storage design; those belong to a future technical specification once product requirements exist.
Household¶
The household is the conceptual owner of everything else in this domain.
It represents the people sharing a home, and by extension sharing food
storage. The domain currently assumes a household is the right unit of
tracking (see docs/strategy/venture-brief.md, working assumptions), but
how a household is represented — a single account, multiple linked
accounts, or something else — is unresolved and out of scope for this
document.
Storage location¶
A storage location is a place within a household's home where food is kept — conceptually including pantry, refrigerator, and freezer, though a real household's storage may not map cleanly onto three tidy categories. Storage location is a first-class domain concept because it materially affects how a stored item behaves over time (a refrigerated item and a pantry item of the same food are not equivalent).
Inventory item¶
An inventory item is the conceptual pairing of a pantry item (what it is) with a specific quantity at a specific storage location, at a point in time. It represents "some amount of this food, here, right now" rather than an abstract catalog entry. Inventory items are expected to be created, updated, and removed as a household's actual food changes.
Quantity tracking¶
Quantity tracking is the conceptual ability to represent how much of an
inventory item exists, and to update that as it's used, replenished, or
disposed of. The domain treats quantity as inherently approximate in
household contexts (see docs/strategy/product-principles.md) rather than
assuming precise, disciplined tracking.
Freshness / estimate concept¶
Freshness is a conceptual, time-sensitive property of an inventory item —
a sense of how likely the item is to still be good, based on estimates
rather than certainty. This concept is intentionally kept separate from
"safety." Freshness estimation touches directly on the standard in
docs/domain/trust-safety-and-food-claims.md, which governs how any such
estimate may be represented to a user. This document only establishes that
"freshness" is a concept the domain needs to reason about — it does not
define how freshness would be calculated, sourced, or displayed.
What this document is not¶
This is domain modeling language for shared understanding across strategy, design, and future engineering discussions. It is not a data model, entity relationship diagram, or schema. Those would be produced as part of a future technical specification, informed by an approved product specification, not inferred from this document.