Module 1: Inventory

⛔ SUPERSEDED 2026-06-11 — Sprig-era feature spec (pre-pivot). The authoritative current design is the locked schema in docs/SCHEMA.md, the module's entry in docs/PROJECT_DECISIONS.md, and the responsibility/seam maps in docs/MODULE_INDEX.md + docs/CROSS_MODULE_CONTRACTS.md. This file is retained for historical feature context only; do NOT treat its scope/table/feature claims as current (it predates the nursery→generic pivot, the HR-out-of-scope cut, the identity/payments/integrations/files extractions, and the schema locks). Superseded note added 2026-06-11.

⚠️ Nursery-First (revised 2026-05-13 per Nursery-Only Focus): Item is the central inventory entity AND CAN carry plant-specific fields directly. No plant_profile indirection. No separate core.item. The item/plant_profile/extensible-attribute model from Phase 4B-1 is cancelled. The original plant-first feature framing in Group 1 is restored as the authoritative model. The Database Schema section below is also reverted to a single-schema layered placeholder. See PROJECT_DECISIONS.md → "Nursery-Only Focus (Locked 2026-05-13)".

Status: ✅ Locked for v1.0 (nursery-first, no refactor pending) Schema: inventory (nursery-facing module; owns its own item / plant master / variant / stock / movement tables directly) Feature count: 94 features in v1.0 — unchanged. Original 94-count stands; the prior "pending recount post-Foundation" annotation is retired. Build estimate: 18–22 weeks for full breadth + AI integration + plant database seed Last updated: 2026-05-13 (Nursery-Only Focus revision; item-first refactor cancelled)

Overview

Inventory is the foundation module. Every other module depends on it. Inventory tracks what the nursery sells (plant masters and their size variants, plus hard goods), where the stock physically lives (sites → zones → bins), and how stock changes over time (receiving, sales, dead count, adjustments, returns).

The module is designed for mid-size growth-stage US retail nurseries ($500K–$5M revenue, 800–3,000 SKUs, 1 site now with multi-site growth path) but the architecture supports all three pricing tiers (Starter / Pro / Enterprise).

Target Customer Profile

• Mid-size growth-stage retail nursery, $500K–$5M revenue
• 800–3,000 SKUs across plant size variants and hard goods
• 5–20 staff, 1 site now with multi-site within 12–24 months
• Spring-weighted seasonality (40–50% of annual revenue March–June)
• Customer mix: 70% retail walk-in, 20% landscape contractors, 10% commercial/HOA
• Currently using: Square, paper, Excel, Lightspeed, or aging Windows ERP

Feature Hierarchy

Group 1: Catalog — what we sell (5 features)

Nursery-first framing (revised 2026-05-13 per Nursery-Only Focus): The item-first / plant_profile refactor is cancelled. The original plant-master + size-variants model is restored as the authoritative design. Plant master IS the item (with plant fields directly on it). Hard goods are a separate concept within the same inventory schema. No core.item, no plant_profile indirection. Variants are children of the plant master as originally specified.

#	Feature	Notes
1.1	Plant master record	Common name, botanical name (genus + species), plant family, primary photo, status. The "parent" that variants attach to. Plant care attributes (1.4) live on this record as columns.
1.2	Size variants per plant	Each plant has multiple sellable sizes (1gal, 3gal, 5gal, 15gal, 24" box, bare root). Each variant: own SKU, barcode, price, cost, qty per zone.
1.3	Plant photos (multiple)	Multiple photos per plant master: full plant, leaf, flower, bark, in-pot.
1.4	Plant care attributes	USDA hardiness zone range, sun (full/part/shade), water (low/med/high), mature size, bloom time, deer-resistant, native, drought-tolerant. Stored directly on the plant master record.
1.5	Hard goods catalog	Non-plant products (pots, soil, mulch, fertilizer, tools, decor). Same SKU/barcode/price/cost/qty structure as plant variants. Separate concept from plant master within the same inventory schema.

Group 2: Stock — where it lives (7 features)

#	Feature	Notes
2.1	Multi-zone stock locations	Custom user-defined names + structured type from preset list (greenhouse, yard, bench area, retail floor, receiving, holding, cold frame, storage, other).
2.2	Bin / sub-zone locations	Custom-named sub-locations within a zone (Row 7, Bench 12-A). Optional. Inherits context from parent zone.
2.3	Multi-site foundation	Schema-ready in v1.0. UI exposed in v1.5. Tenants with multiple sites can be supported by flipping a feature flag.
2.4	Real-time on-hand quantity	Per variant per zone per bin.
2.5	On-hand sync across devices	Multiple devices viewing inventory see the same state in real-time (Supabase Realtime).
2.6	Inventory locking on cart-add	15-min default lock when added to cart; configurable per tenant; manager override available.
2.7	Negative inventory handling	Configurable: allow with warning flag (default) or hard block.

Group 3: Movement — how stock changes (6 features)

#	Feature	Notes
3.1	Receiving workflow	Capture supplier, qty, cost per variant, destination zone, optional photo.
3.2	Inventory auto-increments on receipt	Atomic — receiving and inventory increment happen in one transaction.
3.3	Sales deduction	POS-triggered. Inventory decrements at sale completion.
3.4	Dead count / shrinkage	Reason codes: dead, damaged, theft, returned, given-away, transferred-to-display, other. Photo optional.
3.5	Quick inventory adjustment	Two-tap from phone. Reason required. Audit-logged.
3.6	Returns to inventory	From customer returns: restock or move to dead/damaged pile.

Group 4: Replenishment (3 features)

#	Feature	Notes
4.1	Reorder thresholds	Min qty per variant.
4.2	Low-stock dashboard	Sortable, filterable.
4.3	Vendor records	Name, contact, lead time, payment terms, notes.

Group 5: Identification & Search (7 features)

#	Feature	Notes
5.1	Barcode scanning — camera	Every phone has a camera; this is the default.
5.2	Barcode scanning — Bluetooth scanner	Pro+ tier feature for high-volume operations.
5.3	Plant search — multi-field	Common name, botanical, SKU, barcode, supplier, custom tag.
5.4	Plant search — fuzzy/typo-forgiving	Forgives misspellings, partial words.
5.5	Tag printing — plant tags	Pot stakes, wrap-around tags, hang tags.
5.6	Tag templates	Multiple template formats; editable placeholders.
5.7	Shelf/price labels	Adhesive labels for hard goods on shelves.

Group 6: Governance (3 features)

#	Feature	Notes
6.1	Multi-user with roles	Built-in: owner, manager, cashier. Custom roles in Enterprise tier (v1.5+).
6.2	Audit trail	Every change logged with actor, time, device, reason.
6.3	Audit trail filtering	By user, date, action type.

Group 7: Data Portability (5 features)

#	Feature	Notes
7.1	CSV import — smart column mapping	AI-assisted mapping (header detection + suggestion).
7.2	CSV import — source presets	Lightspeed, Square, QuickBooks, Excel presets in v1.0. Picas CSV import ships v1.1 with guided migration playbook.
7.3	CSV export — inventory snapshot	Full inventory state at point in time.
7.4	CSV export — transaction history	Sales + receiving + adjustments + transfers + dead count.
7.5	Inventory snapshot history	Daily snapshots, 7-year retention.

Group 8: Stock Accuracy (2 features)

#	Feature	Notes
8.1	Stock take / cycle count mode	App locks into counting mode; walk + scan + count workflow.
8.2	Variance report	After stock take: missing/extra, dollar discrepancy, possible reasons.

Group 9: Foundation (2 features)

#	Feature	Notes
9.1	Mobile-first design	Phone primary, tablet secondary. Flutter-built.
9.2	5G always-online with 60-sec offline buffer	NOT full offline-first; assumes mobile data available.

Group 10: Light Purchasing (5 features)

#	Feature	Notes
10.1	Shopping list / "things to order"	Informal checklist owners use when calling vendors.
10.2	Cost change alerts	If receiving cost differs from previous by >X%, flag for review.
10.3	Vendor pricing comparison view	"Lavender: Vendor A $4.50, Vendor B $5.00, Vendor C $4.25." Reads from purchasing.vendor via PurchasingService. Inventory does not own vendor master.
10.4	Basic QuickBooks export	CSV of vendor bills for AP entry.
10.5	Vendor cost history (auto-derived)	Last-paid price per vendor per variant. Auto-derived from purchasing.po_receipt history via PurchasingService.

Group 11: Operational Awareness (4 features)

#	Feature	Notes
11.1	Tax/insurance-ready dead stock report	Formatted for tax write-offs and insurance claims; photos as evidence.
11.2	Quick photo capture from anywhere	Tap to photo any item; attach to variant; for documentation.
11.3	Last-sold price awareness	At POS lookup, see recent sale prices for informed pricing decisions.
11.4	Sale price scheduling	Set future-dated promotional pricing; auto-applies on schedule.

Group 12: Advanced Movement (3 features)

#	Feature	Notes
12.1	Inventory transfer between zones	Move stock from one zone to another within a site.
12.2	Reprint labels from print history	Audit of what tags were printed; quick reprint.
12.3	Bulk operations (multi-select edit)	Select many variants, apply changes en masse.

Group 13: Plant Database & AI Catalog (3 features)

#	Feature	Notes
13.1	Botanical autocomplete from built-in plant database	Pre-loaded with 30K+ cultivars sourced from licensed third-party databases plus USDA PLANTS; staff doesn't enter from scratch.
13.2	AI plant description generation	Bedrock-powered; SEO-friendly description from photo + basic attributes.
13.3	AI attribute auto-fill from photo	Pre-fill USDA zone, sun, water, etc. from plant photo.

Group 14: Advanced Reporting (3 features)

#	Feature	Notes
14.1	Aging report	How long inventory has been in stock; flags dead-stock candidates.
14.2	Find-similar plants suggestions	"We're out of Japanese maple, here are similar options" — matches by attributes.
14.3	AI anomaly detection on adjustments	Patterns in dead count or adjustments that suggest theft or error.

Group 15: Production Tracking (3 features)

#	Feature	Notes
15.1	Production tracking UI	Propagation start dates, ready dates, materials consumed. Schema in v1.0; full Production module spec is Module 7.
15.2	Plant problem / pest tracking per lot	"Lot 47 has spider mites" — note vs quarantine.
15.3	Plant condition grading	A / B / C / Cull rating; same lot can have different grades.

Group 16: AI Vision (3 features)

#	Feature	Notes
16.1	AI plant identification from photo	Customer or staff snaps photo; AI identifies the plant.
16.2	AI bulk photo matching	Upload 50 photos; AI matches them to existing inventory variants.
16.3	AI invoice OCR at receiving	Snap photo of vendor invoice; AI extracts line items for reconciliation.

Group 17: Customer Engagement (1 feature)

#	Feature	Notes
17.1	Customer waitlist for out-of-stock items	When variant goes to zero, customers can join waitlist. When stock arrives, notifications sent.

Group 18: Multi-location & Advanced (3 features)

#	Feature	Notes
18.1	Inventory transfer between sites	Move stock from one site to another. Schema-ready in v1.0; UI exposed in v1.5.
18.2	Per-zone user permissions	"User X can only access greenhouse 2" — Enterprise tier.
18.3	Snapshot history UI	Visual time-travel through inventory state.

Group 19: Enterprise Customization (3 features)

#	Feature	Notes
19.1	Customizable status workflow	Tenant-defined statuses beyond active/inactive.
19.2	Custom fields per variant	Enterprise customers extend the schema without code changes.
19.3	Lot / batch tracking	Track plants by source/sow date for recalls, age-based pricing.

Group 20: International & Special Hardware (2 features)

#	Feature	Notes
20.1	Multi-currency support	Schema-ready in v1.0; USD only in UI. Enabled per tenant later.
20.2	RFID tag support	Niche but Enterprise asks for it. Bulk scan trays/pallets.

Group 21: Data Quality (3 features)

#	Feature	Notes
21.1	Inventory item merge / dedupe tool	Two staff added same plant under different names — merge with history preserved.
21.2	Plant attribute inheritance / templates by category	"New succulent" — pre-fill typical succulent attributes. Pairs with AI auto-fill.
21.3	Receiving discrepancy tracking	Expected qty vs actual qty; track shortages/extras for vendor disputes.

Group 22: Pricing Logic (2 features)

#	Feature	Notes
22.1	Pricing rounding rules	Always end in $.99, $.95, whole dollar — configurable per tenant.
22.2	Markup rules at receiving	Auto-calculate retail from cost (cost × multiplier or absolute markup).

Group 23: Quality Control (3 features)

#	Feature	Notes
23.1	Quarantine / hold flag	Not sellable now, still on books. Awaiting treatment/inspection.
23.2	Receiving damage codes + photo capture per shipment	Cracked pot, root-bound, undersized, dead, wrong variety, etc.
23.3	Tag preview before print	See what tag will look like before sending to printer.

Group 24: Approval Workflows (2 features)

#	Feature	Notes
24.1	Inventory adjustment approval workflow	Threshold-based: adjustments over $X require manager approval.
24.2	Multi-level approval for high-value adjustments	$X requires manager; $Y requires owner.

Group 25: Advanced Search & Discovery (2 features)

#	Feature	Notes
25.1	Plant lookup by vendor SKU / supplier code	When ordering, you know vendor's codes, not yours. Lookup by their code.
25.2	Cross-reference common names	"Sweet potato vine" and "Ipomoea batatas" point to same plant.

Group 26: Specialty Tracking (4 features)

#	Feature	Notes
26.1	Per-specimen care record	For high-value individual plants (specimen trees $500+). Watering, fertilizing, pruning per individual.
26.2	Plant guarantee / warranty tracking	Track warranty expirations, claim history.
26.3	Frost / weather protection plant flags + alerts	"Frost tonight, these 12 plants need to come inside."
26.4	Photo annotation for damage at receiving	Draw arrows/circles on damage photos; resolves vendor disputes.

Group 27: Kits & Bundles (Kit-BOM) (5 features)

Nursery-first framing (revised 2026-05-13): Kits are an inventory SKU type with a bill of materials referencing other inventory variants. All Kit-BOM concepts live in the inventory schema directly. The "item-first / core.item" framing from Phase 4B-1 is cancelled.

#	Feature	Notes
27.1	Kit SKU type	A SKU flagged as kit with a bill of materials referencing component variants.
27.2	Kit component management	Add/remove component variants and quantities per kit; UI for kit composition.
27.3	Kit sale deducts components	When kit SKU sells (POS), each component's qty is deducted from inventory atomically.
27.4	Kit cost calculation	Kit cost = sum of component costs at time of sale (cost basis preserved).
27.5	Kit pricing override	Kit retail price independent of component prices (configurable per kit).

Tier Behavior

Tier	Inventory capability
Starter	Unlimited SKUs. 1 zone, 1 user. All features available within caps.
Pro	Unlimited SKUs, up to 20 zones, up to 10 users. Full feature set.
Enterprise	Unlimited everything. Plus custom fields, custom statuses, custom roles, API access, multi-currency, RFID.

Database Schema

Reverted to single-schema layout (2026-05-13 per Nursery-Only Focus). The Phase 4B-1 layered "core / nursery-facing / vertical-extension" classification is cancelled. All inventory tables live in the inventory schema. Plant master / variants / care attributes / hard goods all live here as originally specified. Full schema definitions remain deferred to the implementation phase; tables follow SCHEMA_CONVENTIONS.md.

Schema: inventory

Core tables (full schema in implementation phase):

• inventory.plant — plant master (includes plant care attributes as columns)
• inventory.variant — sellable size variants of plants
• inventory.hard_good — non-plant products
• inventory.zone — physical zones within a site
• inventory.bin — sub-locations within a zone
• inventory.stock — current on-hand qty per variant per zone/bin
• inventory.movement — every stock change (receive, sale, adjust, transfer, dead, return)
• inventory.cost_history — per-variant cost over time
• inventory.snapshot — daily point-in-time inventory state
• inventory.cycle_count — stock-take session records
• inventory.cycle_count_line — items counted in a session

Additional tables for v1.0 advanced features:

• inventory.tag_template
• inventory.tag_print_log
• inventory.shopping_list_item
• inventory.cost_change_alert
• inventory.adjustment_approval
• inventory.merge_log
• inventory.waitlist
• inventory.frost_alert_subscription
• inventory.specimen_care_log
• inventory.guarantee_record

Vendor master lives in the purchasing schema, not here — see PurchasingService.

Full schema definitions are deferred to implementation phase. Tables follow SCHEMA_CONVENTIONS.md.

API Contract (InventoryService — public methods)

Methods to be defined in detail during implementation, but high-level surface:

• Variant queries: getVariant, listVariants, searchVariants
• Stock queries: getAvailableQty, getOnHandQty, getReservedQty
• Stock mutations: deductStock (called by POS), reserveStock (called by Orders), releaseReservedStock, receiveStock, recordDeadCount, transferStock
• Catalog mutations: createPlant, createVariant, updateVariant, mergeVariants
• Reporting queries: getValuation, getAgingReport, getDeadStockReport, getLowStockItems, getTopSellers, getSlowMovers

Events Emitted

• inventory.stock_changed
• inventory.variant_created
• inventory.variant_updated
• inventory.variant_merged
• inventory.dead_count_recorded
• inventory.adjustment_approved
• inventory.cycle_count_completed
• inventory.cost_change_alert_triggered
• inventory.frost_alert_triggered

Events Consumed

• pos.sale_completed (triggers stock deduction confirmation)
• orders.reservation_created (triggers stock reservation)
• orders.reservation_cancelled (triggers stock release)
• orders.reservation_fulfilled (triggers stock deduction confirmation)
• purchasing.po_received (triggers receiving workflow integration in v1.2+)

AI Features (8 total)

1. CSV import smart column mapping (Group 7)
2. AI plant description generation (Group 13)
3. AI attribute auto-fill from photo (Group 13)
4. Find-similar plants suggestions (Group 14)
5. AI anomaly detection on adjustments (Group 14)
6. AI plant identification from photo (Group 16)
7. AI bulk photo matching (Group 16)
8. AI invoice OCR at receiving (Group 16)

All AI features use AWS Bedrock with Claude Haiku 4.5 unless otherwise specified.

Locked Defaults

• Cart-lock auto-release: 15 minutes (configurable)
• Negative inventory: allow with warning flag (configurable to hard block)
• Snapshot frequency: daily (overnight)
• Snapshot retention: 7 years
• Default cost method: moving average
• Default new staff role: cashier
• Zone naming: custom name + structured type
• Bin naming: custom name only, inherits zone context
• Zone count limits: Starter 1 / Pro 20 / Enterprise unlimited

Out of Scope (for this module)

• EDI with big-box retailers
• Full Material Requirements Planning (MRP)
• Greenhouse environmental controls / IoT sensors
• Labor cost allocation per crop
• Multi-stop greenhouse pick route optimization
• Full GL accounting (use QuickBooks integration)

Gaps Identified from Market Research

Source: See docs/MARKET_RESEARCH_GAPS.md for the master gap registry. Status: All gaps below are Open — pending decision. None have been accepted into scope yet.

Gap #	Gap	What's missing in this module	Research source	Possible options
2	Weather-tied inventory AI	No weather signal feeding reorder forecasting or seasonal demand prediction	Research §6.3.5	Deferred (v1.2) — Couples with full Purchasing launch. See ROADMAP v1.2.
5	Starter 200-SKU cap mismatch	Cap forces upgrade immediately for target nursery (800–3,000 SKUs per research)	Research §10.A tier banding	Accepted — Option (b): unlimited SKUs in Starter; user/site/zone remain capped at 1 each. See MARKET_RESEARCH_GAPS Gap #5 + PROJECT_DECISIONS Pricing.
9	Kit-BOM (kits as inventory records)	Combo pricing exists at POS (10.13); kit-as-inventory-record now added	Research §4.1	Accepted — Option (a): new Group 27 "Kits & Bundles (Kit-BOM)" with 5 features. Inventory count 89 → 94.
12	Plant taxonomy database size	Plan now states 30K+ cultivars (13.1)	Research §5.1	Accepted — Option (b): licensed third-party + USDA PLANTS. 30K+ at v1.0.
13	UV-stable/weatherproof tag substrate	Substrate is a vendor concern, not software	Research §5.1	Rejected — Option (b): substrate documented in customer help docs (vendor recommendations).
15	AI markdown optimization	Sale price scheduling (11.4) is manual; no AI-driven markdown	Research §6.3.5	Deferred (v1.2) — Part of v1.2 AI markdown bundle. See ROADMAP v1.2.
22	Season as first-class variant axis	Currently handled via pricing schedules and out-of-season flags	Research §4.1	Rejected — Option (b): keep as pricing/flag. See OUT_OF_SCOPE.
23	Hyper-local product-level reorder	No local-weather input to AI reorder yet	Research §6.3.5	Deferred (v1.2) — Couples with Gap #2 weather-tied bundle.
26	Price optimization / markdown guidance	No decision support on markdown yet	Research §6.3.5	Deferred (v1.2) — Part of v1.2 AI markdown bundle. See ROADMAP v1.2.
27	Named migration playbooks	CSV import smart mapping (7.1) exists with presets; no named guided migration flow from QuickBooks POS, Square, Lightspeed	Research §2.1 — QuickBooks POS sunset triggered rushed migrations	(a) Build named migration wizards / (b) Document as GTM-only / (c) Defer