ca-grow-ops-manager/specs/inventory-and-materials.md

Feature Spec: Inventory and Materials

Domain: Inventory
Status: Draft
Version: 0.1.0
Last Updated: 2025-12-08

---

Overview

The Inventory and Materials module tracks cultivation supplies (nutrients, pots, IPM products, PPE, CO₂ tanks, filters, soil/media, packaging) with quantity tracking, min/max thresholds, restock prompts, and optional lot/serial linkage to batches for recall support.

---

User Stories

As a Head Grower

• I want to track current inventory levels so I know what's in stock
• I want to set min/max thresholds so I'm alerted when supplies are low
• I want to link material lots to batches so I can trace issues back to specific inputs
• I want to see material usage trends so I can optimize ordering

As a Staff Member

• I want to quickly check if we have enough nutrients for today's feed so I don't run out mid-task
• I want to log material usage so inventory stays accurate

As an Owner

• I want to see material costs per batch so I can calculate profitability
• I want to track supplier performance (quality, delivery time)

As a Compliance Manager

• I want to link material lots to batches so I can support recall investigations

---

Requirements

Functional Requirements

Item Catalog

• Item types:
  • Nutrients (base, additives, supplements)
  • Growing media (soil, coco, rockwool)
  • Pots and containers
  • IPM products (pesticides, beneficial insects)
  • PPE (gloves, masks, suits)
  • CO₂ tanks and regulators
  • Filters (carbon, HEPA)
  • Packaging (jars, bags, labels)
  • Tools and equipment
• Item properties:
  • Name and SKU
  • Category
  • Unit (gallon, pound, each, etc.)
  • Current quantity
  • Min/max thresholds
  • Location (room, shelf)
  • Supplier
  • Lot/serial number (optional)
  • Expiration date (optional)
  • Cost per unit
  • Notes

Inventory Tracking

• Add stock: Log new deliveries with quantity, lot, and cost
• Use stock: Log material usage with quantity, batch, and user
• Adjust stock: Manual adjustments with reason and approval
• Transfer stock: Move items between locations
• Automatic updates: Deduct stock when linked to task completion (future)

Restock Alerts

• Min threshold alerts: Notify when quantity falls below minimum
• Expiration alerts: Notify when items approach expiration
• Restock suggestions: Based on usage trends

Lot/Serial Tracking

• Link lots to batches: Associate material lots with batches for traceability
• Recall support: Query which batches used a specific lot
• Supplier traceability: Track materials back to supplier and purchase order

Reporting

• Current inventory: List of all items with quantities
• Low stock report: Items below min threshold
• Usage report: Material usage by item, batch, period
• Cost report: Material costs per batch
• Expiration report: Items expiring soon

Non-Functional Requirements

• Performance: Inventory list loads in < 500ms
• Data integrity: Stock adjustments require reason and approval
• Accessibility: WCAG 2.1 AA compliant
• Mobile-first: Stock usage logging optimized for tablet

---

Out of Scope (v1)

• Automated reordering (integration with suppliers)
• Barcode/QR code scanning
• Multi-location inventory (single facility only in v1)
• Integration with accounting systems for purchase orders

---

Acceptance Criteria

Item Catalog

• Items can be created with all required properties
• Items can be categorized by type
• Items can be searched and filtered
• Min/max thresholds can be set per item

Inventory Tracking

• Stock can be added with lot and cost
• Stock can be used with batch linkage
• Stock adjustments require reason and approval
• Stock transfers are logged with user and timestamp

Restock Alerts

• Alerts are generated when quantity falls below min threshold
• Alerts are generated for items expiring within 30 days
• Alerts can be dismissed or actioned

Lot/Serial Tracking

• Lots can be linked to batches
• Recall query returns all batches using a specific lot
• Lot history is immutable

Reporting

• Current inventory report displays all items with quantities
• Low stock report displays items below min threshold
• Usage report displays material usage by batch
• Cost report displays material costs per batch

---

Technical Notes

Data Model (Prisma Schema)

model InventoryItem {
  id          String   @id @default(cuid())
  name        String
  sku         String?  @unique
  category    ItemCategory
  unit        String   // gallon, pound, each, etc.
  quantity    Float
  minThreshold Float?
  maxThreshold Float?
  location    String?
  supplierId  String?
  supplier    Supplier? @relation(fields: [supplierId], references: [id])
  costPerUnit Float?
  notes       String?
  lots        InventoryLot[]
  transactions InventoryTransaction[]
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model InventoryLot {
  id          String   @id @default(cuid())
  itemId      String
  item        InventoryItem @relation(fields: [itemId], references: [id])
  lotNumber   String
  serialNumber String?
  quantity    Float
  expirationDate DateTime?
  receivedDate DateTime
  supplierId  String?
  supplier    Supplier? @relation(fields: [supplierId], references: [id])
  batchLinks  BatchMaterialLink[]
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model InventoryTransaction {
  id          String   @id @default(cuid())
  itemId      String
  item        InventoryItem @relation(fields: [itemId], references: [id])
  type        TransactionType
  quantity    Float
  lotId       String?
  lot         InventoryLot? @relation(fields: [lotId], references: [id])
  batchId     String?
  batch       Batch?   @relation(fields: [batchId], references: [id])
  userId      String
  user        User     @relation(fields: [userId], references: [id])
  reason      String?
  approvedBy  String?
  approvedAt  DateTime?
  createdAt   DateTime @default(now())
}

model BatchMaterialLink {
  id          String   @id @default(cuid())
  batchId     String
  batch       Batch    @relation(fields: [batchId], references: [id])
  lotId       String
  lot         InventoryLot @relation(fields: [lotId], references: [id])
  quantityUsed Float
  usedAt      DateTime @default(now())
  userId      String
  user        User     @relation(fields: [userId], references: [id])
}

model Supplier {
  id          String   @id @default(cuid())
  name        String
  contact     String?
  email       String?
  phone       String?
  address     String?
  notes       String?
  items       InventoryItem[]
  lots        InventoryLot[]
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

enum ItemCategory {
  NUTRIENT
  MEDIA
  POT
  IPM
  PPE
  CO2
  FILTER
  PACKAGING
  TOOL
  OTHER
}

enum TransactionType {
  ADD
  USE
  ADJUST
  TRANSFER
}

API Endpoints

• GET /api/inventory/items - List items with filters
• GET /api/inventory/items/:id - Get item detail
• POST /api/inventory/items - Create item
• PATCH /api/inventory/items/:id - Update item
• DELETE /api/inventory/items/:id - Delete item
• POST /api/inventory/transactions - Log transaction (add, use, adjust)
• GET /api/inventory/transactions - List transactions
• GET /api/inventory/lots - List lots
• POST /api/inventory/lots - Create lot
• GET /api/inventory/lots/:id/batches - Get batches using a lot (recall query)
• GET /api/inventory/alerts - Get restock and expiration alerts
• GET /api/inventory/reports/current - Current inventory report
• GET /api/inventory/reports/low-stock - Low stock report
• GET /api/inventory/reports/usage - Usage report
• GET /api/inventory/reports/cost - Cost report
• GET /api/inventory/suppliers - List suppliers
• POST /api/inventory/suppliers - Create supplier

UI Components

• InventoryList - Filterable list of items
• InventoryCard - Item summary card with quantity gauge
• InventoryDetail - Full item view with transaction history
• InventoryForm - Item creation/editing
• TransactionForm - Add/use/adjust stock form
• LotTracker - Lot/serial tracking interface
• RecallQuery - Recall investigation tool
• RestockAlerts - Alert dashboard
• InventoryReports - Reporting interface

---

Dependencies

• Batches and Rooms module (for batch linkage)
• Tasks module (for automatic stock deduction on task completion)
• Authentication (for user attribution and RBAC)

---

Risks & Mitigations

Risk	Impact	Mitigation
Inventory drift (physical vs. system)	High	Regular physical counts; adjustment approval workflow
Lot tracking errors	Medium	Clear UI; validation; immutable lot history
Restock alert fatigue	Medium	Configurable thresholds; smart batching of alerts

---

Future Enhancements (Post-v1)

• Barcode/QR code scanning for quick stock updates
• Automated reordering based on usage trends
• Integration with supplier systems for purchase orders
• Multi-location inventory (multiple facilities)
• Predictive restock suggestions based on batch schedules
• Integration with accounting systems (QuickBooks, Xero)