Business Workflows

About this document

ShilaTeq is the operating system for a stone yard. This page traces the end-to-end business processes a yard runs on the platform — from the day a block arrives at the gate to the day it leaves on a truck as a paid, GST-invoiced order — and documents the state machines that govern every stone, quote, order, and dispatch.

Each workflow below has three parts: a short intro, a diagram (flowchart or state diagram), and the key business rules that the platform enforces. Rules are tagged ✅ Confirmed (directly enforced by the product) or 💡 Inferred (a reasonable reading of behaviour) where it matters.

Related reading: User Journeys · Modules · Reports & Analytics · Notifications · User Roles

The big picture

Every workflow on this page is a segment of one long value chain: stone in → money out. This map shows how the pieces connect.

1. 👤 User Onboarding & Account Setup

ShilaTeq is a provisioned, not self-service platform. There is no public "sign up" button; a yard is set up for the owner, who then provisions their own staff from inside the app.

Key rules

✅ Owner accounts are provisioned externally, not self-signed-up. The owner signs in with email + password and lands on the Dashboard.
✅ Workers are created by an admin from the Workers page. When the admin taps Enable login, the worker receives a username and can thereafter sign in with username only (no email, no visible password prompt) — designed for low-literacy, phone-only shop-floor staff.
✅ A "driver" is not a separate account. Any login-enabled worker becomes a driver the moment an admin assigns them to a dispatch; they then see only their own deliveries.
✅ Yard configuration lives in Settings: business profile, GSTIN and default GST rate, carrying-cost rate (default 14%/yr 💡 illustrative default), and inventory aging thresholds (default amber 90 days / red 180 days).
✅ A demo-data reset in Settings wipes operational data while preserving the yard and owner login — useful for onboarding trials.

2. 📦 Procurement Lifecycle (PO → Receive → Blocks)

Buying stone starts with a Purchase Order to a supplier and ends with the yard's inventory growing by one row per block — each already carrying a cost basis.

Key rules

✅ A PO is created via a 3-step wizard with supplier and line details; it opens in status ordered with a sequential code PO-### and paid_amount = 0.
✅ Receiving is atomic and one-click. Confirming receipt flips the PO to received and, in the same operation, fans each unreceived line out into a new inventory block — sized, typed, and stamped with a QR code and a cost basis (the purchase price per sq ft). Each new block back-links to the PO line it came from.
✅ Received blocks arrive as available stock, immediately quotable and sellable.
✅ Supplier payments are recorded against the PO; the PO's paid_amount is derived from confirmed supplier payments (never typed directly), mirroring the customer-side payment model.
💡 A PO can be cancelled before receipt; cancelled POs never spawn blocks.

3. 🏷️ Inventory Tagging & QR Minting

Every block gets a permanent digital identity — a QR code — the moment it enters the yard, whether it arrived via a PO or was tagged by hand at the gate.

Key rules

✅ Two intake paths, one identity system. Blocks created by receiving a PO are auto-tagged; blocks tagged by hand use the 3-stage Add Block wizard (identity → grade/pricing → photos). Both end with a minted QR code.
✅ 12 required fields to tag a block. Selling price is required for admins but optional for workers — workers tag physical stock; pricing is the owner's job.
✅ Photos are downscaled to roughly 150 KB each (up to 5), keeping the catalog and lists fast.
✅ The QR code is the block's lifelong handle. It can be printed as an 80×110 mm label, scanned by phone camera, and resolves to a public, price-safe block identity card at /qr/….
✅ Catalog opt-in is per block. A block only appears in the public showroom if it is available and the yard chooses to show it; its price is shown publicly only if show_price_publicly is on (otherwise "On request").

4. 🪚 Cutting / Manufacturing (Partial-Cut Engine)

The manufacturing heart of ShilaTeq. A worker feeds a block into the gangsaw, records how much stone was consumed and what slabs came out, and the platform computes recovery %, wastage, remnant, and recovery-adjusted slab cost — all from a phone, offline if needed.

The math (✅ Confirmed)

Quantity	How it's derived
Output area	Sum of each slab's L × W
Wastage	Consumed area − output area
Recovery %	Output ÷ consumed × 100
Slab material cost / sq ft	Block purchase price × consumed ÷ output — wastage raises the surviving slabs' unit cost
Remainder	Block remaining − consumed

Key rules

✅ Wastage is priced in. Because a block's whole material cost is spread over the actual slab output, cutting loss automatically raises the per-sq-ft cost of the slabs that survive — the yard sees true, recovery-adjusted economics, never a rosy nominal cost.
✅ The parent block always closes to status cut (terminal) with zero remaining. The leftover stone is the remnant.
✅ A remnant becomes a brand-new available block (-R1, -R2, …) that inherits the parent's variety/origin/pricing and is instantly quotable — nothing is stranded.
✅ Every cut writes an immutable cut-event ledger row (recovery %, wastage) — a permanent audit trail of yield.
✅ Cutting is idempotent and offline-safe. A double-tap or an offline replay of the same cut can never cut a block twice.
💡 Admins retain a simpler legacy "full cut" from the block detail screen (no consumed input, no remnant) for quick conversions.

See the business-logic reference for the exact formulas and null-safety rules.

5. 📄 Quotation Lifecycle

A quotation is a price proposal that holds no stock. The same available block can appear on many drafts at once — quotes compete for stock, they don't lock it.

Key rules

✅ Quotes don't hold stock — by design. Nothing is reserved until conversion, so a single block may be quoted on many drafts simultaneously.
✅ Expiry is computed at read time from the quote's valid-until date and lazily persisted — a quote past its date reads as expired without a nightly job.
✅ Conversion is race-guarded. Converting re-checks that every line is still available (both in the UI and on the server); if any block was reserved or sold in the meantime, conversion is refused.
✅ On successful conversion, an order is created in status reserved, each block/slab flips to reserved, and the quotation is marked converted with a back-link to the order.
✅ Customer-facing send uses a WhatsApp quotation template (see Notifications); the printed quotation carries a catalog QR footer.

6. 🛒 Order Lifecycle & Reservation (Payment-Gated)

An order is the commercial spine of the platform. It moves through a strict, payment-gated pipeline and holds real stock from the moment it is created.

Two ways to create an order

Key rules

✅ Every advance past reserved requires at least one confirmed payment. The platform blocks Start Processing and Create Dispatch until a confirmed payment exists (see Payment Lifecycle below).
✅ Reservation is atomic — all or nothing. The secure reservation locks every requested block/slab and flips them in a single compare-and-swap. If any one is no longer available, the whole reservation is rolled back (zero partial reservations), the order shell is discarded, and the user is told the block is no longer available.
✅ Concurrency policy is "refresh, don't retry." On a double-booking conflict the client refetches fresh state rather than blindly retrying a stale intent — so two salespeople can never sell the same slab.
✅ Soft credit-limit gate on direct orders. If the customer's total exposure (existing unpaid orders + this one) would exceed their credit limit, ShilaTeq warns and requires an explicit override to proceed. A null limit means unlimited.
✅ Reserved orders are editable. Lines can be added/removed with automatic re-reserve/release of stock, with a floor at the amount already paid.
✅ Cancelling any pre-sold order releases its reserved stock back to available.

7. 💰 Payment Lifecycle

Payments are what unlock the order pipeline. ShilaTeq never lets you type a paid amount directly — it's always derived from confirmed payments, so the money and the stock can never drift apart.

Key rules

✅ paid_amount is always derived, never written by hand — it equals the sum of that order's confirmed payments. The supplier side works identically for POs.
✅ One confirmed payment unlocks the pipeline. Until it exists, the order cannot leave reserved.
✅ Overpayment is capped both in the UI (against remaining balance) and on the server (confirmed payments cannot exceed the order total from surviving lines).
✅ Store credit spends like cash. Applying a customer's store credit posts a confirmed credit-note payment, so it folds into paid_amount exactly like a cash receipt — and is capped to the lesser of available credit and outstanding balance.
✅ Payment modes: cash, UPI, card, bank transfer, plus the system-generated credit-note. 💡 No online payment gateway — receipts are recorded manually.
✅ The Sold cascade (triggered on delivery or explicit completion) freezes a COGS snapshot onto each order line, so later price edits never rewrite historical margin.

8. 🧾 Invoicing (GST Invoice Generation)

One order, one tax invoice. ShilaTeq generates an India-compliant GST invoice with the correct CGST/SGST/IGST split, HSN code, and amount in words.

Key rules

✅ One invoice per order (enforced) — with a sequential INV-#### number minted automatically.
✅ GST split is exact. For an intra-state sale the tax is split into CGST and SGST (a remainder trick keeps the halves adding up to the penny); for an inter-state sale it's a single IGST line. Place-of-supply is a manual toggle at generation time.
✅ Worked-stone HSN is 6802 across invoices.
✅ The invoice is a frozen snapshot — line items, buyer name/GSTIN/state are captured at generation; the seller block is re-rendered live from the yard profile at print time.
✅ The printed invoice includes amount-in-words (Indian crore/lakh/thousand grouping) and a catalog QR footer that turns every invoice into a showroom link.

9. 🚚 Dispatch, Gate Pass, Driver & Delivery

Dispatch closes the loop: it prints a gate pass, hands the order to a driver, gives the customer a public live-tracking link, and — on delivery — auto-completes the order to sold.

Dispatch state machine (✅ Confirmed)

Key rules

✅ Dispatch is SOP-gated. Creating one requires the order to be processing/shipped, to have a confirmed payment, and to have no active dispatch already.
✅ Creating a dispatch advances the order to shipped as a side effect and mints a DN-### gate pass with a random public tracking token.
✅ The gate pass auto-prints as a self-contained A4 "Gate Pass / Loading Slip" with an embedded tracking QR, live seller block, item list, and signature areas — clearly marked "not a tax invoice." It's reprintable anytime.
✅ Drivers see only their own deliveries. An assigned driver's delivery list shows only their dispatches, with forward-only Mark In Transit → Mark Delivered buttons, in English or Hindi.
✅ Delivery auto-sells the order. A delivered dispatch triggers the Sold cascade: the order becomes sold, its blocks/slabs become sold with sale price and date, a COGS snapshot is frozen onto each line, and any active worker assignments complete. No manual "mark sold" step is needed.
✅ Public tracking needs no login. Customers open /track/<token> to see live delivery stage; the page shows safe fields only (no prices).

10. ↩️ Returns / RMA (Restock vs Scrap + Store Credit)

Returns are handled per line, with a clear choice: put good stone back on the shelf, or scrap damaged stone and book the loss — with any customer overpayment turning into store credit.

Key rules

✅ Returns are allowed only on sold orders. Attempting a return on any other status is refused.
✅ Restock returns good stone to the available pool with no loss booked. Scrap marks it damaged — and damaged stone never re-enters the sellable pool; it's excluded from every selector, finder, and stock-value snapshot.
✅ Every scrap writes a damage_log row (DMG-####, a reason, and an estimated loss on a COGS basis) that surfaces as a dashboard write-off alert and a "Write-offs" line in the P&L report.
✅ Store credit is booked incrementally. Only the new overpayment a return introduces is credited to the customer's store-credit ledger, so repeated returns on the same order can never double-count credit. The order's paid amount is left untouched — the delta becomes the customer's money.
✅ Line accounting is careful. A full-quantity return deletes the order line entirely (a zeroed line could otherwise be wrongly re-released later); a partial return shrinks the line's quantity, total, and cost.

Store-credit mechanics are covered in the business-logic reference.

11. 🌐 Public Catalog → Lead → Reply

The yard's online 3D showroom turns anonymous web visitors into qualified leads that land in the admin inbox — and a single WhatsApp reply moves the lead forward automatically.

Lead state (✅ Confirmed)

Key rules

✅ No login, no data leakage. The public catalog reads only safe, narrow data: available blocks, safe columns, price gated per block ("On request" when hidden), zone-level location only — never purchase price, supplier, or notes.
✅ Lead capture is validated and yard-scoped. A submission needs a name and phone; the referenced block is only attached if it truly belongs to that yard.
✅ Leads land as new in the admin inbox (new / contacted / closed).
✅ A WhatsApp reply auto-advances the lead from new to contacted and pre-fills a friendly reply (with a catalog promo footer) — the reply is the status change.

The showroom experience is detailed in Product Overview and Screens & Pages.

12. 📊 Reporting Workflow

Reporting in ShilaTeq is a pure pipeline: live operational data → computed metrics → plain-language insights → decisions and exports. It's always up to date because it recomputes from source, never from a stale summary table.

Key rules

✅ A date range drives the window P&L (revenue, COGS, gross/net profit) while balance-sheet-style snapshots (stock value, aging, receivables/payables) are always "as of now," never date-filtered.
✅ Every KPI carries a period-over-period delta so the owner sees direction, not just level.
✅ Insights are generated in plain language — up to a handful of findings like "Revenue up 12% vs last period" or "₹X of stock has aged past 180 days — consider a clearance push."
✅ Exports are one control: branded PDF, a genuinely-recomputed weekly deep-dive, multi-sheet Excel, and Print — plus per-panel CSV and chart-as-PNG.

Full detail lives in Reports & Analytics.

13. 🔔 Notification & Alert Workflow

ShilaTeq surfaces the things that need a human: toasts confirm actions, the notifications bell and dashboard alerts rank what needs attention, and WhatsApp carries messages to customers — all kept live by an event-driven refresh belt.

Key rules

✅ Two independent alert engines. The header notifications bell ranks leads, aging stock, receivables, PO/AP due, and stale reservations; the dashboard runs its own action-card engine (overdue AR, ready-to-dispatch, unmarked attendance, wages/supplier payable, write-offs).
✅ Toasts confirm every action — a green success or a red error — so users always know a save landed.
✅ WhatsApp is the messaging layer — five zero-API deep-link templates (quote, invoice, dispatch+tracking, lead reply, payment reminder).
✅ Everything stays live via an event-driven refetch, a cross-tab poll, and a realtime channel — no manual reload needed.

Every mechanism is documented in full in Notifications.

Appendix — All State Machines at a Glance

The definitive lifecycle of each core entity. These are server-enforced — the platform refuses any transition not shown here.

Block

Slab

Purchase Order

Quotation

Order

Dispatch

Part of the ShilaTeq Product Documentation Hub. See also: User Journeys · Reports & Analytics · Notifications · the business-logic reference.