Inventory Management — Form Specifications

Module slug: inventory · UX/forms agent · 2026-05-02 Models the flow of consumables — samagri (rice, ghee, flowers, dhoop, oils), kitchen supplies, books, prasadam ingredients — through purchase, donation-in-kind, dispense, and event-driven kits. Sanskrit terminology preserved per framework HTML; samagri kit names match the framework's dropdown options.

---

Form 5.1 — Inventory Item Master

Purpose: Register a stock-keeping unit (SKU) with category, unit of measure, and stock thresholds. Who fills: Stores manager · once per item · revisited if thresholds change or item discontinued.

Field	Type	Required	Options / Validation	Default	Help
SKU	text	Yes	uppercase alphanum + hyphen, unique per tenant	auto: INV-{seq}	E.g. INV-RICE-PR
Item Name	text	Yes	255 chars	—	E.g. Rice (Sona Masuri)
Item Name (Sanskrit)	text	No	Devanagari, VijayaDV preserved	—	E.g. तण्डुल
Samagri Category	dropdown	Yes	Samagri / Kitchen-Raw / Kitchen-Spice / Flowers / Dhoop-Incense / Oils-Ghee / Books / Cleaning / Office-Supply / Prasadam-Ingredient / Other	—	Drives reports
Sub-category	text	No	40 chars	—	E.g. grain, pulse
Unit of Measure (primary)	dropdown	Yes	kg / g / litre / ml / piece / packet / metre / bundle / dozen	kg	Internal stock UoM
Secondary UoM	dropdown	No	same options	—	E.g. packet
Conversion Factor (primary per secondary)	number	conditional	required if Secondary set; step 0.0001	1	E.g. 1 packet = 0.5 kg → 0.5
Is Perishable	checkbox	No	—	unchecked	If checked, batch/expiry capture mandatory at GRN
Shelf Life (days)	number	conditional	required if Perishable	—
HSN Code	text	No	20 chars	—	For GST
GST Rate (%)	number	No	0.00–28.00 step 0.01	0
Minimum Threshold (qty)	number	No	step 0.001 ≥ 0	—	Triggers low-stock alert
Maximum Threshold (qty)	number	No	step 0.001 ≥ Min	—
Reorder Quantity	number	No	step 0.001 ≥ 0	—	Suggested PO size
80G Eligible (donation-in-kind)	checkbox	No	—	unchecked	Disallowed for jewellery, perishables
Active	checkbox	Yes	—	checked
Notes	textarea	No	1000 chars	—

Submit action: POST /api/inventory/items. Creates row in inventory_items. Stock-level rows are created lazily per branch on first movement. Related forms: Vendor Catalog Entry (5.2) attaches per-vendor rates; Samagri Kit Template Editor (5.8) lists items.

---

Form 5.2 — Vendor Catalog Entry

Purpose: Record a vendor's rate for a specific inventory item, with payment terms and lead time. Who fills: Procurement officer · per vendor-item pair · revisited when rate changes.

Field	Type	Required	Options / Validation	Default	Help
Vendor	lookup	Yes	from Vitta vendors master	—	Single vendor master across modules
Item	lookup	Yes	from inventory_items	—
Rate per UoM (INR)	number	Yes	step 0.0001 ≥ 0	—	Per primary UoM of item
Currency	dropdown	No	INR / USD	INR	Future-proofing
Minimum Order Qty	number	No	step 0.001 ≥ 0	—
Lead Time (days)	number	No	0–365	—	Days from PO to delivery
Last Purchased On	date	No	≤ today	—	Auto-populated from latest GRN
Payment Terms	dropdown	Yes	Advance / Net-7 / Net-15 / Net-30 / COD	Net-15
Is Preferred Vendor	checkbox	No	—	unchecked	Only one preferred per item; UI enforces
Notes	textarea	No	500 chars	—

Submit action: POST /api/inventory/vendors/{vendor_id}/catalog. Upsert on (vendor_id, item_id). Related forms: Purchase Order Compose (5.3) auto-fills rate from this catalog.

---

Form 5.3 — Purchase Order Compose

Purpose: Create a PO for one vendor with multiple item lines; supports event-triggered POs. Who fills: Procurement officer · per PO · revisited at approval / send / cancel.

Field	Type	Required	Options / Validation	Default	Help
PO Number	text	Yes	unique per tenant	auto: PO-{YY}-{seq}
PO Date	date	Yes	≤ today	today
Branch	dropdown	Yes	tenant's branches	current	Procuring branch
Vendor	lookup	Yes	from vendors	—
Expected Delivery Date	date	No	≥ PO Date	PO Date + vendor lead time	Auto-suggested
Fund Tag	dropdown	Yes	General / Annadana / Building / FCRA / Endowment	General	Mirrors Vitta fund segregation
Triggered by Event	lookup	No	from event_instances	—	Set when generated from event indent
Triggered by Indent	lookup	No	from event_samagri_indents	—	Set automatically when from indent
Notes	textarea	No	1000 chars	—

Sub-form (line items, repeatable):

Field	Type	Required	Options / Validation	Default	Help
Item	lookup	Yes	from inventory_items	—
Quantity	number	Yes	step 0.001 > 0	—
UoM	read-only	Yes	from item primary	—
Rate	number	Yes	step 0.0001 ≥ 0	from vendor catalog	Editable override
Line Total	read-only	computed	qty × rate	—

Footer: Subtotal · Tax (GST computed from item rates) · Total — all read-only.

Submit action: POST /api/inventory/purchase-orders saves as draft. Approval (separate action) sets status to approved. Send action triggers Comms email to vendor with PDF attachment ("Purchase Order on Letterhead" template). Related forms: Vendor Catalog (5.2) auto-populates rates; Goods Receipt (5.4) closes the loop.

---

Form 5.4 — Goods Receipt (GRN)

Purpose: Record items physically received against a PO; reconcile expected vs actual quantity. Who fills: Stores in-charge · per delivery · revisited only for inspection-failure correction.

Field	Type	Required	Options / Validation	Default	Help
GRN Number	text	Yes	unique per tenant	auto: GRN-{YY}-{seq}
Linked PO	lookup	Yes	active POs of vendor	—	Disables already-completed POs
Receipt Date	date	Yes	≤ today	today
Received By (Staff Member)	lookup	Yes	from members	current user's member-id
Vendor Invoice Number	text	No	63 chars	—	For Vitta payable
Vendor Invoice Date	date	No	≤ today	—
Inspection OK	checkbox	Yes	—	checked	Uncheck triggers rejection notes
Rejection Notes	textarea	conditional	required if not OK	—
Vehicle / Mode of Delivery	text	No	127 chars	—	E.g. KA-09-XX-1234, Hand-carried
Notes	textarea	No	1000 chars	—

Sub-form (line items pre-populated from PO, editable):

Field	Type	Required	Options / Validation	Default	Help
Item	read-only	Yes	from PO line	—
Ordered Qty	read-only	—	—	—
Received Qty	number	Yes	step 0.001 ≥ 0 ≤ Ordered	Ordered	Variance highlighted
Condition	dropdown	Yes	Good / Damaged / Partially-Damaged	Good
Batch Number	text	conditional	required if item perishable	—
Expiry Date	date	conditional	required if item perishable; ≥ today	—
Line Notes	text	No	255 chars	—

Submit action: POST /api/inventory/purchase-orders/{po_id}/receipts. Increments stock_levels per line. Auto-creates vendor_payables row in Vitta tagged with PO's fund. Updates PO line received_quantity and PO status (partially-received or completed). Related forms: Purchase Order (5.3) is parent; Stock Level View (5.7) reflects new balances.

---

Form 5.5 — Donation-In-Kind Entry

Purpose: Register a donor's contribution of physical goods (samagri, food, books, equipment); 80G eligible if item category permits. Who fills: Reception / store officer · per donation event · final-state.

Field	Type	Required	Options / Validation	Default	Help
Donor (Member)	lookup	Yes	from members (search/create)	—	If new, opens member-create modal first
Donation Date	date	Yes	≤ today	today
Branch	dropdown	Yes	tenant's branches	current	Receiving branch
Item	lookup	Yes	from inventory_items	—
Quantity	number	Yes	step 0.001 > 0	—
UoM	read-only	Yes	from item primary	—
Fair Market Value (INR)	number	conditional	required if 80G	—	For 80G certificate
80G Eligible	checkbox	conditional	enabled only if item category permits	depends on item	Auto-disabled for jewellery, perishables
Receipt Number	text	conditional	auto-generated if 80G	auto: DKR-{YY}-{seq}	Reserved on save
Occasion	text	No	127 chars	—	E.g. Datta Jayanti, daughter's wedding
In the Name Of	text	No	255 chars	—	If donation is in another's name (memorial)
Acknowledgement Channel	dropdown	No	Email / WhatsApp / Postal / In-Person / None	Email	Triggers Comms send
Notes	textarea	No	1000 chars	—

Submit action: POST /api/inventory/donations-in-kind. Increments stock_levels. If 80G, generates certificate via Vitta and queues acknowledgement via Comms. Donor tagged with donor-in-kind. Related forms: Inventory Item Master (5.1) — is_80g_eligible cascades; Stock Level View (5.7) reflects increment.

---

Form 5.6 — Dispense Record

Purpose: Issue stock from inventory for a stated purpose — event, daily nitya pooja, kitchen, gift, sale, maintenance, or wastage. Who fills: Stores in-charge · per dispense (often barcode/QR-driven later) · daily volume.

Field	Type	Required	Options / Validation	Default	Help
Item	lookup	Yes	from inventory_items with current stock	—	Shows balance
Branch	dropdown	Yes	tenant's branches	current	Dispensing branch
Dispense Date	date	Yes	≤ today	today
Quantity	number	Yes	step 0.001 > 0; ≤ current stock (soft warn if exceeds)	—
UoM	read-only	Yes	from item primary	—
Purpose	dropdown	Yes	Event / Daily-Nitya / Kitchen / Gift / Sale / Maintenance / Wastage	—	Drives next-fields
Linked Event	lookup	conditional	required if Purpose = Event	—	from event_instances
Linked Indent	lookup	conditional	optional if Purpose = Event	—	from event_samagri_indents
Issued To (Member)	lookup	No	from members	—	E.g. archaka, kitchen-staff
Recipient Description	text	conditional	required if Purpose = Gift / Sale and recipient not a member	—	E.g. visiting acharya
Force-Negative override	checkbox (admin)	No	—	unchecked	If checked, allows dispense exceeding stock; audit-logged
Notes	textarea	No	1000 chars	—

Submit action: POST /api/inventory/dispense. Decrements stock_levels. Rejects on negative balance unless force-negative is set (then logs audit_event). Related forms: Generate Samagri Indent (5.9) often pre-populates dispense; Maintenance Completion (Form 6.3) writes purpose=Maintenance dispenses.

---

Form 5.7 — Stock Level View (Filter Form)

Purpose: Browse current stock with filters; trigger reorder POs from low-stock results. Who fills: Stores manager · query-only · daily glance.

Field	Type	Required	Options / Validation	Default	Help
Branch	dropdown	No	tenant's branches + "All"	All
Category	dropdown (multi)	No	same as item category	—
Sub-category	text	No	partial match	—
Show only Low-Stock	checkbox	No	—	unchecked	Items below minimum_threshold
Show only Perishables	checkbox	No	—	unchecked
Search by Name / SKU	text	No	partial match	—
As-of Date	date	No	≤ today	today	Computes historical stock

Output table columns: SKU · Name · Category · Branch · Current Qty · UoM · Min · Max · Reorder Qty · Last Movement · Status badge (OK / Low / Out / Over).

Submit action: GET /api/inventory/stock-levels with query params. From a low-stock row, "Reorder" button opens Form 5.3 pre-filled with item, suggested vendor (preferred from catalog), suggested qty (reorder_quantity). Related forms: Purchase Order Compose (5.3) is the reorder destination.

---

Form 5.8 — Samagri Kit Template Editor

Purpose: Define a reusable kit of items needed for a specific seva or festival; multipliable per event. Who fills: Pradhana Archaka or Procurement officer · once per kit · revisited rarely.

Field	Type	Required	Options / Validation	Default	Help
Kit Code	text	Yes	unique per tenant	auto: KIT-{seq}
Kit Name	dropdown (with "Custom")	Yes	Maha Ganapati Homa Kit / Marriage Kit (Bride Side) / Marriage Kit (Groom Side) / Maha Shivaratri Abhisheka / Custom	—	"Custom" reveals free-text Kit Name input
Kit Name (Sanskrit)	text	No	Devanagari, VijayaDV preserved	—	E.g. महागणपतिहोमसामग्री
Description	textarea	No	2000 chars	—	What ritual/event this serves
Bound Seva	lookup	No	from sevas (existing DISA)	—	Optional bind for auto-pull on event
Bound Seva Category	lookup	No	from sevaCategories	—	Broader bind
Active	checkbox	Yes	—	checked

Sub-form (line items, repeatable; drag-and-drop ordering):

Field	Type	Required	Options / Validation	Default	Help
Item	lookup	Yes	from inventory_items	—	Type-ahead search
Quantity per Unit-Event	number	Yes	step 0.001 > 0	—	E.g. 0.5 kg per kalyanotsavam
UoM	read-only	Yes	from item primary	—
Is Critical	checkbox	No	—	unchecked	If missing, ritual cannot proceed; flagged red
Substitute Items	lookup (multi)	No	from inventory_items	—	Acceptable substitutes
Line Notes	text	No	255 chars	—	E.g. yellow only, fresh

Submit action: POST /api/inventory/samagri-kits. PATCH replaces all lines. Preview pane shows "what gets bought when this kit fires for 1 event" with vendor rate compare. Related forms: Generate Samagri Indent (5.9) consumes this kit; Inventory Item Master (5.1) is the line source.

---

Form 5.9 — Generate Samagri Indent (from Kit + Event)

Purpose: Produce an indent worksheet for an event from a kit template × multiplier; show stock vs shortfall, route to dispense / PO. Who fills: Event coordinator (post event-confirmation) · per event · revisited if event scope changes.

Field	Type	Required	Options / Validation	Default	Help
Event	lookup	Yes	from event_instances (status confirmed or planned)	—
Kit Template	lookup	conditional	required unless seva-bound kit auto-resolved	from event's seva → kit	Override allowed
Quantity Multiplier	number	Yes	step 0.01 > 0	1	E.g. 50 kalyanotsavams × 1 kit = 50
Indent Generation Date	date	Yes	≤ Event Date − 1 day	today
Branch	dropdown	Yes	tenant's branches	event's branch
Notes	textarea	No	1000 chars	—

Output worksheet (per kit line): Item · Required Qty · Current Stock at Branch · Shortfall · Suggested Action (Dispense / PO) · Suggested Vendor · Suggested Rate · Estimated Cost.

Worksheet actions per row: Dispense (calls Form 5.6) · Add to PO (groups by suggested vendor and opens Form 5.3 pre-filled).

Submit action: POST /api/inventory/events/{event_id}/generate-indent. Creates event_samagri_indents parent + lines. Status starts draft. Approval moves to approved. Fulfilment can be dispense-from-stock, purchase-order, or mixed. Critical lines block fulfilment until resolved. Related forms: Samagri Kit Template (5.8) is the source; Purchase Order (5.3) and Dispense Record (5.6) are downstream.

---

Workflow notes

1. First-time setup order: 5.1 (items) → 5.2 (vendor rates) → 5.8 (kit templates). Then transactional forms (5.3, 5.4, 5.5, 5.6) flow as operations occur.
2. Stock movement chain: every PO line eventually closes via 5.4 (GRN) → stock incremented; every dispense via 5.6 → stock decremented; donations-in-kind (5.5) → stock incremented.
3. 80G eligibility logic: items must have is_80g_eligible=true AND donor must consent. Jewellery and perishables auto-disable.
4. Force-negative dispense: allowed only with admin role; every such dispense gets an audit_event row.
5. Event-driven flow: Event (Form 7.x) → Indent (5.9) → branches into Dispense (5.6) for stocked items + PO (5.3) for shortfalls.
6. Kit critical lines: if marked critical and stock + PO won't arrive in time → blocks event confirmation in the Events module.