Shelfery Domain Glossary¶
This glossary defines terms used when discussing the Shelfery problem domain (home food storage and pantry management). Definitions are kept general and conceptual on purpose — they describe the domain language, not an implementation, database schema, or data model. A future product specification may formalize some of these terms differently.
Pantry item — A distinct kind of food or consumable a household tracks or could track (e.g. "canned tomatoes," "rice"). A pantry item is a concept of what something is, independent of how much of it exists or where it's stored.
Storage location — A place within a home where food is kept. The domain currently recognizes pantry, refrigerator, and freezer as the primary conceptual storage locations, though a household's real storage arrangement may be more varied (e.g. a garage shelf, a second fridge). Storage location matters because it affects how food behaves over time.
Quantity — How much of a pantry item is present at a given storage
location. Quantity is a household-facing concept and is expected to often
be approximate rather than precise (see
docs/strategy/product-principles.md).
Unit — The measure a quantity is expressed in (e.g. count, weight, volume). Units in household contexts are often informal (e.g. "a jar," "a bag") rather than standardized, and the domain should accommodate that rather than forcing precision.
Expiration estimate — A non-authoritative, estimated point in time (or
range) after which a pantry item is expected to decline in quality or
safety. The word "estimate" is deliberate: this is not a guarantee. See
docs/domain/trust-safety-and-food-claims.md for how estimates must be
represented.
Use-by date — A concept, not a guaranteed fact, referring to
manufacturer or authoritative guidance indicating a date after which a
product may no longer be safe to consume. Shelfery does not currently
define an authoritative source for use-by data; see
docs/domain/trust-safety-and-food-claims.md.
Best-by date — A concept, not a guaranteed fact, referring to manufacturer or authoritative guidance indicating a date after which quality (not necessarily safety) may decline. Best-by and use-by are distinct concepts and must not be conflated in product content.
Waste event — The conceptual moment a household disposes of a pantry item because it was not used in time, spoiled, or otherwise became unusable. This is a domain concept describing something that could be observed or recorded, not a defined feature.
Restock — The conceptual act of a household acquiring more of a pantry item, replenishing what has been used or wasted. Like the other terms here, this describes a domain event conceptually, not a specific product workflow.
Notes on usage¶
- These terms are meant to create shared vocabulary for discussing the domain across strategy, design, and any future engineering work — they are not a data schema. A schema, if and when one is created, belongs to a future product/technical specification, not this glossary.
- Terms related to food safety and freshness estimation are governed by
docs/domain/trust-safety-and-food-claims.md; when in doubt, that document takes precedence over how a term is used elsewhere.