RetailOS — Detailed User Manual (Forms, Fields & Connections)

Companion to the Usage Guide. The usage guide explains what the system does and how the flows work; this manual is the field-level reference: for every form it lists each input — name, type, whether it's required, its default, its validation — and, crucially, how that form connects to the others (what it looks up, what it feeds, and what happens on submit). This manual is served at /manual. Base URL: https://goretailos.com. Admin paths need a signed-in staff session; storefront paths carry a shop slug (/store/<shopSlug>/…).

How to read this manual

💡 Prefer learning inside the app? Open Quick Tours (/admin/tours, under Administration in the sidebar): a guided walkthrough of the whole system plus a detailed step-by-step tour for every module your shop has enabled — POS, Restaurant, E-commerce, Inventory, Purchasing, Accounting, HR & Payroll, Growth and the AI assistant. Each step takes you to the real screen and tells you exactly what to do there — tours never change your data, and your progress is saved so you can resume any time.

Each form is documented as:

• Purpose / Access / Backend — what it's for, which roles may use it, and the server function + database table(s) behind it (so developers can trace it).
• A Fields table with these columns:

• A Connections block:
• Selects / references — other forms this one reads from (foreign keys). Example: a Product selects a Category.
• Feeds / used by — forms and screens that consume this record downstream.
• Cross-form effects — what submitting does elsewhere (stock movements, ledger postings, sequence numbers).

Convention used everywhere: a field ending in _id is a pointer to another form's record. The manual names the human form (e.g. "Category") and the pointer (category_id) together.

The tenant model (read this first)

Everything hangs off one root record: the shop. Every table in the system carries a shop_id, and the server always filters by the shop you have active in the header switcher. A single login can be a member of several shops (see Team & Roles) and switch between them; data never crosses between shops. Branch-bound staff are further limited to one branch within a shop.

Header controls. The top bar carries the organization switcher (your own shops appear under My organizations; platform-level accounts also see an All organizations (platform) group with search), a branch switcher, a notifications bell, a language selector, and a Toggle theme button that flips the admin between light and dark appearance (saved per browser). Switching organizations swaps everything at once — data, currency and timezone — with no cross-shop leakage; your newest organization starts completely empty.

Because of this, shop_id (and often branch_id) is an implicit, auto field on every form below — set from your session/active shop, never typed — so the per-form tables don't repeat it unless it behaves unusually.

Data model at a glance

The forms wire together along these spines (arrow = "points at / looks up"):

Catalog spine

• Product → looks up Category (category_id, a self-nesting tree via parent_id), Brand (brand_id), Tax rate (tax_rate_id).
• Product → has many Variants (product_variants, the sellable unit). Each Variant fans out to Barcodes, Prices, Variant costs (private, never public), Product images, and Inventory balances (one per stock Location).

Selling spine

• Order (order_channel = pos / online / ai) → Order items (→ Variant) + Payments (→ Payment method) + Receipts; optionally → Customer (customer_id).
• Return (→ Order) → Return items (→ Order item) → Refunds.
• POS: Register → Cash session → Cash movements; Register users grant till access.

Inventory spine

• Inventory movement (movement_type) is the ledger of stock; it updates Inventory balances (Variant × Location).
• Transfer → Transfer items, moving stock between Locations (from_location_id → to_location_id) on receipt.
• Stock count → Stock count items post adjustments.

Purchasing spine

• Supplier → Purchase order → PO items (→ Variant); Goods receipt (→ PO) → Receipt items; Supplier invoice (→ PO); Supplier payment (→ Supplier / Invoice).

Accounting spine

• Every posting writes a balanced Journal entry → Journal entry lines (→ Account; Accounts form a tree via parent_id, typed by account_type). Expenses (→ Expense category, Account). Payment methods, Bank accounts, Cash accounts.

Storefront + AI

• Cart → Cart items (→ Variant). Customer → Customer addresses, Wishlists. Store look/behaviour: Storefront settings / themes / pages / navigation / banners / sections / policies.
• AI permissions gate assistant actions; Knowledge documents → Knowledge chunks; Conversations → Messages, Tool calls, Action approvals, Alerts.

A full table-by-table foreign-key index is in Appendix B.

Contents

1. Accounts, Team & Shop Settings
2. Catalog
3. Inventory
4. Purchasing & Accounting
5. Sales — POS, Registers, Orders & Sync
6. Storefront Editor & AI (Admin)
7. Storefront — Customer Forms
8. Reports
9. Promotions, Loyalty & Marketing
10. Manufacturing (BOM & costing)
11. Restaurant
12. CRM, Segments & Analytics
13. HR & Payroll
14. Business Intelligence
15. Advanced Procurement

• Appendix A — Enumerations (shared choice lists)
• Appendix B — Tables ↔ forms index

Accounts, Team & Shop Settings

Sign in / Sign up — /auth (?mode=signup)

• Purpose: Staff authentication and new-account registration for the admin portal.
• Access: Public (unauthenticated). Already-signed-in users are redirected to /admin.
• Backend: Supabase Auth client SDK (no server fn / zod) — supabase.auth.signUp / supabase.auth.signInWithPassword → auth.users (a DB trigger mirrors into profiles). mode=signup search param preselects the sign-up view.

Fields

Connections

• Feeds / used by: Session drives all _authenticated/* routes; full_name/email surface in Team → Members. New signup with emailRedirectTo=/admin.
• Cross-form effects: Successful auth navigates to /admin (which routes to Onboarding if the user has no shop). Signup without a session shows "check your email to confirm."

After signing in you land on the admin dashboard (/admin) — KPI cards with trends, a 14-day sales chart, category mix, profitability, AI insights and an alert centre.

Forgot password — /auth (inline action)

• Purpose: Trigger a password-reset email.
• Access: Public (sign-in view only).
• Backend: supabase.auth.resetPasswordForEmail(email, { redirectTo: /reset-password?next=%2Fadmin }) (client SDK).

Fields

Connections

• Cross-form effects: Email link lands on Reset password with next=/admin.

Reset password — /reset-password (?next=<relative path>)

• Purpose: Set a new password from a recovery link (used by both staff and storefront customers).
• Access: Public, but the Update button is enabled only once a recovery/SIGNED_IN session is present.
• Backend: supabase.auth.updateUser({ password }) (client SDK) → auth.users.

Fields

Connections

• Cross-form effects: On success redirects to next (default /admin) after ~1.2s.

Onboarding — create shop — /onboarding (auth-gated)

• Purpose: Provision a new tenant (shop) for the signed-in user, who becomes owner.
• Access: Any authenticated user (creator is inserted as owner).
• Sign out: A Sign out button in the header ends the current session and returns to /auth — use it if you signed in with the wrong account before creating a shop.
• Backend: createShop (src/lib/shop.functions.ts) → provisionShop (src/lib/shop.server.ts) → tables shops, shop_users, and many child tables (see cross-form effects).

Fields (authoritative = createShop zod schema)

Connections

• Feeds / used by: Creates the tenant consumed by every admin/POS/storefront route; owner membership drives getMyShops and the role matrix.
• Cross-form effects (all in provisionShop, one batch of inserts):
• shops (with settings = DEFAULT_SHOP_SETTINGS), shop_users (creator → owner)
• branches: "Main Branch" (MAIN, is_default, default business_hours)
• registers: "Register 1" (REG1); inventory_locations: "Main Store" (is_default)
• payment_methods: Cash / Card / Bank Transfer / Store Credit (disabled) / Cash on Delivery
• tax_rates: "Standard VAT" rate 0 (is_default)
• accounts: 14-line chart of accounts (is_system)
• document_sequences: 8 doc types (order/receipt/invoice/purchase_order/return/credit_note/debit_note/goods_receipt)
• ai_permissions: 19 capability rows; storefront_settings (1 row); storefront_navigation (5); storefront_policies (4); expense_categories (5)

Accept invitation — /invite/$token

• Purpose: Let an invited user join a shop's team.
• Access: Preview is public; accepting requires being signed in with the invited email.
• Backend: getInvitationPreview (unauth) and acceptStaffInvitation (auth) (src/lib/team.functions.ts) → team.server.ts → tables staff_invitations (read + update) and shop_users (upsert).

Fields

Preview returns (read-only, auto): status, expired, role, email, shopName.

Connections

• Selects / references: Resolves shop name via staff_invitations.shop_id → shops(name).
• Cross-form effects on accept: upsert into shop_users (shop_id, user_id, role, branch_id, is_active=true, onConflict shop_id,user_id); set staff_invitations.status='accepted', accepted_at, accepted_by; audit log; navigates to /admin.

Invite a staff member — /admin/team

• Purpose: Send a staff invitation and generate a shareable invite link.
• Access: owner, admin — page requires can("settings"); server enforces requireRole(..., ADMINS).
• Backend: inviteStaffMember (src/lib/team.functions.ts) → inviteStaff (team.server.ts) → table staff_invitations.

Fields

Connections

• Selects / references: Branch (from Branches) via branch_id.
• Feeds / used by: Row appears in Invitations list; link consumed by Accept invitation. Returns { link: <origin>/invite/<token> } shown with a Copy button.
• Cross-form effects: Insert into staff_invitations; audit staff.invite.

Revoke invitation — /admin/team (Invitations list)

• Purpose: Cancel a pending invitation.
• Access: owner, admin.
• Backend: revokeStaffInvitation → revokeInvitation → staff_invitations (set status='revoked').

Fields

Edit / deactivate member — /admin/team (Members list)

• Purpose: Change a member's role/branch or (de)activate them.
• Access: owner, admin.
• Backend: updateTeamMember (src/lib/team.functions.ts) → updateMember (team.server.ts) → table shop_users.

Fields

Connections

• Cross-form effects: Updates shop_users; audit staff.member.update. Guard: cannot demote or deactivate the last active owner ("must always have at least one active owner").

Shop Settings — /admin/settings

• Backend (all sections except Tax rates & Branches): updateShopSection (src/lib/shop.functions.ts) writes shops columns (the shop patch) and/or merges into shops.settings[<section>] jsonb (the settingsPatch). Section role gate enforced server-side via has_shop_role; the write uses the service-role client after the check.
• Access per section: Business, Localization, Tax, Document numbering, Customers & credit → owner, admin. Receipts, POS, Inventory, Pricing, Purchasing, Business hours, Notifications → owner, admin, manager. Lower roles see the section read-only.

Business profile — settings section business

Writes shops columns + settings.business.tax_id.

Localization — settings section localization (writes shops columns)

Tax — settings section tax (+ inline tax_rates editing)

Tax rates sub-table (writes tax_rates directly): rate (number, saved on blur), is_default (radio — one default).

Receipts — settings section receipt

Printer (this device only, saved to localStorage — not DB): Printer type (browser / escpos-bridge), Paper width, Bridge URL, Printer name, Auto-cut, Kick cash drawer.

Point of sale — settings section pos

Inventory — settings section inventory

Delivery charges — settings section delivery

• Purpose: Storefront delivery pricing — a default policy plus optional per-zone overrides resolved exact city → country-wide → default. Charges are computed server-side at checkout and set the order's shipping_total. Backend: retail.server.ts (resolveDeliveryPolicy / computeDeliveryCharge / deliveryFreeThreshold), read via getShopDeliverySettings; stored under shops.settings.delivery.

Storefront effect: the checkout country / city selectors pick the matching zone; the header shows the free-delivery banner when enabled and a threshold is set.

Pricing & discounts — settings section pricing

Purchasing — settings section purchasing

Bank transfer — settings section payments

Bank-account details shown to customers who pick bank transfer at online checkout. Owner/admin only.

Connections — surfaced on the storefront checkout when the shopper selects Bank transfer, and on the order confirmation so they can complete the transfer.

Expenses — settings section expenses

Approval policy for expenses recorded in Accounting. Owner/admin only.

Connections — governs Record expense (/admin/accounting): above-threshold expenses wait for approval before posting to the ledger.

Customers & credit — settings section customers

Governs customer accounts and whether staff may sell on credit / udhaar (pay later) at the till. Owner/admin only.

Connections — read by the POS Payment screen to decide whether the signed-in user may sell on credit; the unpaid balance of a credit sale posts to the customer's Accounts Receivable and is settled later from Sales → Record payment. See Payment screen → Credit (pay later).

Document numbering — settings section documents

This section writes only to shops.settings.documents. The live document_sequences rows (their own prefix/padding/next_number) are created at onboarding and are not edited here.

Business hours — settings section hours

Weekday/weekend open & close times (text, e.g. "09:00"), closed days (comma-separated), holiday notice (textarea).

Notifications & alerts — settings section notifications

Low stock alerts, Daily briefing, End-of-day summary — all toggles, default on.

Branches & registers — read-only summary

Read-only overview of branches and registers; "Manage registers →" links to /admin/registers.

Connections (Shop Settings overall)

• Selects / references: POS section → Branches (default_branch_id) and Registers (default_register_id); Inventory → Inventory locations (default_location_id); Tax → Tax rates.
• Feeds / used by: shops.settings drives POS guardrails, pricing/discount limits, purchasing approvals, receipt rendering, storefront hours, and notifications. Business/localization columns render on receipts, invoices, storefront and admin/POS formatting.
• Cross-form effects: Business writes shops columns + settings.business.tax_id; other sections merge into shops.settings[<section>]; Tax-rate edits write tax_rates directly. Writes bypass the owner/admin-only shops RLS via the service-role client after the section role check (so managers can save their permitted sections).

Tables owned: shops (PK id; created_by→auth user; unique slug), profiles (PK id→auth.users), shop_users (shop_id→shops, user_id→auth user, branch_id→branches), staff_invitations (shop_id→shops, branch_id→branches, invited_by/accepted_by→auth users, unique token), branches (shop_id→shops), document_sequences (shop_id→shops, unique (shop_id,doc_type)), storefront_settings (shop_id→shops, unique). Provisioned/referenced: registers, inventory_locations, tax_rates, payment_methods, accounts, ai_permissions, storefront_navigation, storefront_policies, expense_categories, audit_logs (all shop_id→shops).

Store Data Manager — /admin/data-manager

• Purpose: Per-store bulk data tools — filter, bulk-update, bulk-delete, insert/seed and (owner-only) reset any of your store's own tables from one screen, without writing raw SQL.
• Access: owner / admin only; Reset is owner-only. Every action is audited. No schema change / migration — it operates on the existing tenant tables.
• Backend: server functions scoped to the active shop; writes can never reach another shop's rows.

Workflow

1. Pick a table — grouped as Catalog, Customers & suppliers, Operations, Sales & finance, Config. A couple (team members, audit log) are view-only for safety.
2. Filter — build conditions (column · operator · value); operators include equals / not-equals, greater / less, contains, in (comma list) and is-empty / not-empty, with a Match ALL (AND) / Match ANY (OR) toggle. A compiled query preview shows exactly what will run.
3. Preview — returns the matching row count plus a sample of rows before you change anything.
4. Bulk update sets one or more columns on every matching row; Bulk delete requires typing DELETE to confirm. Both re-check the previewed count before applying, are capped at 50,000 rows, and are audited.
5. Add / seed rows — paste JSON (an array of objects) or CSV (first row = column names); shop_id is added automatically.

Foreign-key dependency resolver — if a delete is blocked by related records (a foreign key), a popup lists the referencing rows per table with Delete these or Set null (unlink). If clearing one of those is itself blocked, a nested popup opens — resolve down the chain, then delete again.

Reset (owner only) — wipe Transactional, Catalog & CRM, or Everything for the store, keeping setup/config (accounts, tax, registers, branches, locations, payment methods, storefront, team). Type RESET to confirm; a blocked reset offers the same dependency resolver.

Safety model: owner/admin only (Reset owner-only) · own-store only (always shop_id-scoped) · no raw SQL · typed confirmations (DELETE / RESET) · a 50,000-row cap · protected read-only tables (team members, audit log) · every action audited.

Subscription & usage — /admin/subscription

• Purpose: Your free trial, per-module licenses, commercial plan and resource consumption in one place. Backend: getShopResourceUsageFn (usage.functions.ts) + the SaaS plan/billing functions.
• Usage tab — Resource usage: how much your store has consumed vs what remains, per category: File storage (product images, payment proofs, HR documents — enforced), Database (records across products, orders, customers, stock), AI (assistant messages, last 30 days), Network (data sent/received through the app in the last 30 days — uploads and storefront media; CDN-cached traffic isn't counted), Team members (enforced when your plan sets a limit), Monthly active users (staff + customer accounts that signed in during the last 30 days — informational, sign-ins are never blocked) and Customers.
• Limits: Your plan's numbers are real for three things — file storage (uploads stop with a clear "Storage limit reached" message at the cap, and a server-side storage policy is the hard backstop so the cap can't be bypassed), team members (inviting, accepting an invite or reactivating someone over the plan's user limit is refused with "You've reached your plan limit…") and AI knowledge documents. The remaining plan quotas in the table below stay informational. Any active license lifts the free-trial caps; the platform team can set individual allowances above your plan — contact support.
• Need more? Limits are adjustable per store: the platform team can set individual overrides (e.g. a larger storage allowance as part of your agreement) from the operator console — contact support. The Usage tab always shows the limits that actually apply to your store.
• Module licenses & access: Access to each of the 14 modules is governed by the Module licenses panel (managed by the platform/operator team, not editable by the shop). On a new store an active free trial covers every module; afterwards each module needs an active license (recorded when payment is received out-of-band). Month grants stack from the current period end; a custom end date cannot shorten an active license (it must be revoked first); a Lifetime grant never expires and absorbs later grants. Hard enforcement follows the platform's LICENSING_ENFORCED rollout flag — while it is off (the current default), licensing is informational and never blocks operational functionality. Note: holding any active module license moves the store from the Trial tier to the Licensed tier, which also raises the enforced resource caps (e.g. file storage from the trial 500 MB to the licensed allowance).

Catalog

Available for sale (hide internal items). Products, categories and brands each carry an Available for sale toggle (is_online, default on). Turn it off to make an item internal-only — e.g. raw materials, packing supplies, or a supplier-only brand/category: it is hidden from both the online storefront and POS product search, while staying fully usable in inventory, purchasing and the admin catalog. This is separate from Active (the archive flag): Active off = archived everywhere (also removed from POS and product selectors); Available for sale off = kept internally but not sold. Because the default is on, existing items are unaffected until you switch it off.

New / Edit Product — /admin/products

• Purpose: Create or edit a catalog product with its media, merchandising flags, tax default and full variant matrix.
• Access: owner, admin, manager (server requireRole(..., MANAGERS)). Page requires auth; save is role-gated.
• Backend: saveProductFn (src/lib/catalog.functions.ts) → saveProduct (src/lib/catalog.server.ts) → products (+ cascades to product_variants, variant_costs, prices, barcodes, inventory_movements, inventory_balances). Images via saveProductImagesFn → product_images.

Fields (product level)

Variant Builder sub-form (src/components/admin/VariantBuilder.tsx)

Attribute matrix: the attribute-name field is a creatable combobox — choose an existing attribute (EntitySelect attributes), or type a new name and press Enter to create it inline (ensureAttributeFn → product_attributes + product_attribute_values); then tick its values → Generate variants builds the cartesian product. A bulk-apply bar sets price/cost/sale_price/weight/opening_stock/tax_rate_id/is_active across all or selected rows.

Number fields select-on-focus. Numeric inputs in the builder (cost, price, sale price, weight, opening stock) select their existing value when you click into them, so typing cleanly replaces a leading "0".

Opening stock posts to the ledger. Entering opening stock with a cost sets on-hand quantity and average cost and books a balanced journal entry Dr Inventory (1200) / Cr Owner Equity (3000) for the opening value (Σ opening_stock × cost) when the product is created, so the GL inventory asset matches the operational balance. Posting is best-effort — if the shop's chart of accounts lacks those accounts or the target period is closed, the stock still saves and the journal is skipped. (Changing a product's stock later via the editor posts a quantity adjustment only, with no journal — matching manual stock adjustments; value inventory changes through a Purchase order → Supplier invoice or an opening-balance journal.)

Product Images sub-form (saveProductImagesFn)

Connections

• Selects / references: Category (category_id), Brand (brand_id), Tax rate (tax_rate_id), Attributes (product_attributes/product_attribute_values).
• Feeds / used by: POS (barcode lookup, sale lines; internal-only is_online=false items are excluded from POS product search), Storefront (status=active and available-for-sale), Inventory (balances/movements), Purchasing, Labels.
• Cross-form effects: opening stock → inventory_movements(opening)+inventory_balances+journal_entries (Dr Inventory 1200 / Cr Owner Equity 3000); cost → variant_costs (private); price → product_variants.price (fires pricing_version trigger); sale price → prices; barcode → barcodes.

Save errors show the real reason. When a save or submit fails — here or anywhere else in the admin — the message now names the actual cause (e.g. a duplicate SKU, a validation problem, or a permission block) instead of a generic "Could not save…".

Barcode generate / attach — /admin/products (variant panel + builder "Gen")

• Purpose: Generate or manually attach EAN-13 / CODE128 barcodes to a variant; deactivate old ones.
• Access: panel (generate/attach/deactivate) = owner, admin, manager, inventory; builder "Gen" & bulk-generate = owner, admin, manager.
• Backend: panel → generateBarcodeFn / attachBarcodeFn / deactivateBarcodeFn / listVariantBarcodesFn (src/lib/barcode.functions.ts); builder/bulk → generateBarcodeFn / bulkGenerateBarcodesFn (src/lib/catalog.functions.ts). Both → barcodes.

Generation uniqueness: barcode.server uses a shop-scoped sequence (ean13FromSequence, prefix 20); catalog.server uses random makeEan13 (prefix 200). "Bulk-generate missing" issues EAN-13 for every variant lacking one. Scan to find (Products page): lookupBarcodeFn resolves an active code to variant+product for search/POS.

Category create / edit — /admin/categories

• Purpose: Manage hierarchical catalog categories (menu, category pages, product grouping).
• Access: UI permission="products"; server write INVENTORY_ROLES.
• Backend: saveMasterDataFn (entity categories) → categories.

Connections — self parent_id; tax_rate_id→tax_rates; used by products (category_id), storefront menu/category pages, filters. Delete blocked while referenced by products or child categories (archive instead).

Brand create / edit — /admin/brands

• Access: UI permission="products"; server write INVENTORY_ROLES. Backend: saveMasterDataFn (entity brands) → brands.

Connections — used by products (brand_id), storefront brand filters/pages. Delete blocked while products reference it.

Attribute + values — /admin/attributes

• Purpose: Define variant attributes (Size, Colour…) and allowed values; feed the variant matrix.
• Access: UI permission="products"; server write INVENTORY_ROLES.
• Backend: attributes → saveMasterDataFn (entity attributes) → product_attributes; values → saveMasterDataFn (entity attribute_values) → product_attribute_values. The variant builder's attribute-name field is a creatable combobox that adds new attributes inline via ensureAttributeFn.

Attribute

Attribute value sub-form

Connections — value attribute_id→product_attributes; feeds VariantBuilder → product_variants.attributes. Attribute delete blocked while it has values.

Tax rate create / edit — /admin/tax

• Access: UI permission="settings" (owner, admin); server write MANAGERS (manager can write via API though UI hides it).
• Backend: saveMasterDataFn (entity tax_rates) → tax_rates.

Connections — used by products, categories, and variant/line tax resolution across POS & online; fires tax_version trigger. Delete blocked while referenced by products, categories or sold order lines; default must be reassigned before delete.

Barcode labels print — /admin/labels

• Purpose: Select variants, pick a size/fields, print a barcode label sheet (no DB writes).
• Access: any authenticated shop member (reads only).
• Backend: labelCatalogFn (src/lib/catalog.functions.ts) reads product_variants (+ products, barcodes); render via BarcodeLabel (JsBarcode).

Connections — reads primary barcodes.code, variant price/sku, product name, shop name/logo; output goes to window.print only.

Bulk import — /admin/import

• Purpose: Import products / suppliers / inventory from CSV or XLSX: upload → map columns → validate → commit.
• Access: owner, admin, manager (validate & commit).
• Backend: validateImportFn / commitImportFn (src/lib/import.functions.ts). Products commit → products, product_variants, variant_costs, prices, barcodes, inventory_movements, inventory_balances.
• Published on commit: new products are created live — status = active and is_online = true — so they show on the storefront, restaurant menu and POS immediately (like manually-created products). Re-importing an existing product (matched by slug/SKU) updates it and leaves its current published state untouched.

Wizard controls

Products import target fields

(Suppliers import → suppliers; Inventory import → inventory_*.) Validate cross-checks existing categories, brands, variant SKUs and barcodes, returning per-row ok/warning/error counts. Commit skips error rows, imports ok+warning, audit-logged; products grouped by name → one product with N variants.

Tables owned: products (category_id→categories, brand_id→brands, tax_rate_id→tax_rates; unique shop_id+slug), product_variants (product_id→products; unique shop_id+sku; extra DB cols not in UI: compare_at_price, track_inventory, low_stock_threshold, reorder_point, reorder_quantity), product_attributes (unique shop_id+code), product_attribute_values (attribute_id→product_attributes), product_images (product_id→products, variant_id→product_variants), prices (variant_id→product_variants; price_type='sale'), variant_costs (variant_id→product_variants; private cost), barcodes (variant_id→product_variants; unique shop_id+code, partial-unique on active; type/source/is_primary/is_active), categories (self-FK parent_id, tax_rate_id; unique shop_id+slug), brands (unique shop_id+slug), tax_rates (is_default exclusive). Import also touches inventory_movements/inventory_balances and suppliers.

Inventory

Manual stock adjustment — /admin/inventory

• Purpose: Post a signed (+/-) quantity correction against a variant at the shop's default location, with a reason.
• Access: Route is admin-authenticated; the write is a client-side Supabase insert/update governed by inventory_movements/inventory_balances RLS (inventory roles). See role matrix.
• Backend: inline applyAdjustment in the route → direct writes to inventory_movements + inventory_balances.

Fields

Connections

• Selects / references: Variant via variant_id; Location implicit via default location_id.
• Feeds / used by: updated balance read by POS / Products / Dashboard low-stock; movement shown in "Recent movements".
• Cross-form effects: each post writes one inventory_movements row and updates/creates the inventory_balances row.

Reorder / stock defaults — /admin/settings (Inventory section)

• Purpose: Shop-wide stock defaults (low-stock threshold, reorder point/quantity, default location, negative-stock rule).
• Access: see role matrix (settings-section gate).
• Backend: updateShopSection (src/lib/shop.functions.ts) → shops.settings.inventory.

Per-variant overrides (low_stock_threshold, reorder_point, reorder_quantity) exist on product_variants but are not editable in the current UI. These feed AI reorder recommendations and Dashboard "Low stock priority" (variant value ?? default).

Create transfer (draft → send → receive) — /admin/transfers

• Purpose: Move stock between two locations through draft → requested → approved → shipped → received.
• Access: create/edit/ship/receive = INVENTORY_ROLES (owner, admin, manager, inventory); approve = MANAGERS. Cancel disabled once shipped.
• Backend: createTransferFn, updateTransferItemsFn, transitionTransferFn (src/lib/inventory-ops.functions.ts) → inventory_transfers, inventory_transfer_items; on ship/receive → postInventory (inventory_movements + inventory_balances).

Header fields

Line items (transferItemSchema)

Auto/computed record fields: transfer_number (nextDocNumber(..., "transfer", "TR-"), unique per shop), status (default draft; enum draft/requested/approved/shipped/received/cancelled), created_by, per-transition *_by/*_at stamps, and per-line received_quantity (default 0, set at receipt, editable). The Receive step sends receivedQuantities keyed by transfer-item id; Ship validates source availability.

Connections

• Selects / references: From/To via from_location_id/to_location_id; lines via variant_id.
• Feeds / used by: Ship posts transfer_out (−) at source; Receive posts transfer_in (+) at destination — both write inventory_movements + inventory_balances; audit transfer.<status>.
• Cross-form effects: stock only leaves source on ship and only lands at destination on receive; draft/requested/approved move no stock.

Stock count (start → count → review → post) — /admin/stock-counts

• Purpose: Physical count vs expected, then post variance adjustments to balances.
• Access: create/save = INVENTORY_ROLES; approve = MANAGERS.
• Backend: createStockCountFn, saveStockCountProgressFn, approveStockCountFn (src/lib/inventory-ops.functions.ts) → stock_counts, stock_count_items; approve → postInventory.

Create fields

Count-sheet line items (stock_count_items)

Save progress sets status='counting', counted_by. Approve/post posts a count-type movement for every non-zero diff (qty = counted − expected), sets status='completed', approved_by, approved_at, completed_at. It then values the net variance at each variant's cost (variant_costs.avg_cost, else cost_price) and posts one balanced GL journal so the perpetual Inventory account tracks the reconciliation: shrinkage (stock down) posts Dr COGS 5000 / Cr Inventory 1200, overage (stock up) posts Dr Inventory 1200 / Cr COGS 5000. Period-guarded and best-effort — balances are the source of truth and are never rolled back if the chart of accounts lacks 1200/5000 or the period is closed.

Connections

• Selects / references: Location via location_id; items via variant_id; scope via categories.
• Feeds / used by: approved variances update inventory_balances; a balanced journal_entries/journal_entry_lines pair (reference_type='stock_count') values the net variance to Inventory 1200 vs COGS 5000; audit stock_count.approved.
• Cross-form effects: posting a count writes inventory_movements (type count) + updates inventory_balances for each non-zero variance, and mirrors the net cost change to the ledger so the balance sheet Inventory line and P&L stay correct.

Location create / edit — /admin/locations

• Purpose: Manage stock locations that hold balances and receive transfers/counts.
• Access: UI permission inventory; server write = INVENTORY_ROLES.
• Backend: saveMasterDataFn / setMasterDataActiveFn / deleteMasterDataFn (src/lib/masterdata.functions.ts, entity inventory_locations) → inventory_locations.

Connections — references Branch via branch_id; owns the inventory_balances/inventory_movements rows; supplies location options to transfers, counts, adjustments, and the settings default location.

Branch create / edit — /admin/branches

• Purpose: Physical trading locations scoping staff, registers, stock locations and reporting.
• Access: UI permission settings; server write = ADMINS (owner, admin).
• Backend: saveMasterDataFn / setMasterDataActiveFn / deleteMasterDataFn (entity branches) → branches.

Connections — referenced by inventory_locations.branch_id and registers.branch_id; drives branch scoping for locations, registers, staff and reporting.

Tables owned: inventory_balances (unique (location_id, variant_id); FKs location_id→inventory_locations, variant_id→product_variants), inventory_movements (FKs location_id, variant_id; enum movement_type; polymorphic reference_type/reference_id), inventory_locations (FKs shop_id, branch_id→branches), inventory_transfers (unique (shop_id, transfer_number); from_location_id/to_location_id→inventory_locations; enum transfer_status), inventory_transfer_items (transfer_id→inventory_transfers, variant_id→product_variants), stock_counts (FKs shop_id, location_id; counted_by/approved_by), stock_count_items (stock_count_id→stock_counts, variant_id→product_variants), branches (shop_id→shops), registers (branch_id→branches). Reorder defaults live in shops.settings.inventory, with nullable per-variant overrides on product_variants.

Purchasing & Accounting

Two admin pages hold most of these forms: Purchasing & suppliers (/admin/purchasing) and Accounting (/admin/accounting). The master-data pages (Suppliers, Chart of accounts, Expense categories, Payment methods) share the generic MasterDataPage component → saveMasterDataFn / setMasterDataActiveFn / deleteMasterDataFn (src/lib/masterdata.functions.ts). Financial writes (invoices, payments, expenses) run through server functions gated by FINANCE_ROLES (owner, admin, manager, accountant).

Supplier — quick add — /admin/purchasing

• Purpose: Fast supplier capture inline on the purchasing page.
• Access: purchasing roles (client insert governed by suppliers RLS).
• Backend: direct supabase.from("suppliers").insert(...).

Supplier — full record — /admin/suppliers

• Purpose: Maintain the supplier master used by POs, receipts and invoices.
• Access: UI permission="purchasing". Backend: saveMasterDataFn (entity suppliers) → suppliers.

Connections — referenced by purchase_orders.supplier_id, supplier_invoices.supplier_id; delete blocked while purchase orders reference it (masterdata.server guard).

Purchase order — /admin/purchasing (New purchase order)

• Purpose: Raise a PO against a supplier with one or more product lines, each with its own quantity and unit cost.
• Access: purchasing roles (client writes governed by RLS).
• Backend: direct client writes → purchase_orders + purchase_order_items; PO number from document_sequences (doc_type purchase_order).

Pick a supplier, then add one row per product, each with its own quantity and unit cost. Use + Add product to add rows and the row's remove control to delete them; a live running total sums every line as you type. The same product can't appear twice on one PO — combine it into a single line (duplicates are blocked).

The AI assistant can also create multi-line POs via create_purchase_order (ai-actions.server.ts) subject to the AI permission matrix.

Expandable detail, Edit & Cancel. In the purchase-orders list, click a PO row to expand an inline detail table with one row per line — Product · Ordered · Received · Unit cost · Line total. From that expanded detail, and only while nothing has been received on the PO, two actions are available:

• Edit — reopens the form pre-filled so you can change the supplier and replace the line items; the PO number and status are preserved.
• Cancel PO — sets the status to cancelled after a confirm prompt.

Once any goods are received, Edit and Cancel disappear and a short note explains the order can no longer be changed — editing a received PO would require reversing already-posted stock and cost postings, which isn't supported.

Connections — references Supplier (supplier_id) and Variant (variant_id, per line); consumed by Receive goods and Supplier invoice (prefill).

Receive goods — /admin/purchasing (per-PO "Receive goods" button)

• Purpose: Post a goods receipt for an open PO — full ordered quantity, no form fields.
• Access: purchasing roles. Backend: direct writes → goods_receipts + goods_receipt_items, inventory_movements (type purchase), inventory_balances, variant_costs (upsert), PO status='received'; GRN number from document_sequences (doc_type goods_receipt).

Cross-form effects — each line adds stock (inventory_movements purchase + inventory_balances), updates cost (variant_costs.cost_price/avg_cost), stamps purchase_order_items.received_quantity, and flips the PO to received. A goods receipt updates stock and cost operationally only — it posts no journal entry; the inventory asset and the payable are booked when the matching supplier invoice is posted (invoice-time recognition).

Supplier invoice — /admin/purchasing (New supplier invoice)

• Purpose: Record a supplier bill (draft), then Post / Cancel it.
• Access: FINANCE_ROLES. Backend: saveSupplierInvoice / postSupplierInvoiceFn / cancelSupplierInvoiceFn / createInvoiceFromSourceFn (src/lib/purchasing.functions.ts) → supplier_invoices.

Actions: Post (draft → posted, writes the journal entry Dr Inventory / Cr Accounts Payable for stock items — this is when purchased stock becomes a GL asset), Cancel (only when nothing paid). Connections — Supplier (supplier_id), optional PO (purchase_order_id) / goods receipt (goods_receipt_id); feeds AP ageing and "Outstanding by supplier".

Supplier payment — /admin/purchasing (Record a payment)

• Access: FINANCE_ROLES. Backend: recordSupplierPaymentFn → supplier_payments (+ journal, updates invoice paid_total/status).

Cross-form effects — increments the invoice's paid_total, moves it to partially_paid / paid, and posts a balanced journal entry (Dr AP / Cr Cash or Bank).

Record expense — /admin/accounting (Overview tab)

• Purpose: Record an operating expense and post it to the ledger.
• Access: FINANCE_ROLES. Backend: recordExpense (src/lib/accounting.functions.ts) → recordExpenseAndPost → expenses + journal_entries.

Cross-form effects — writes an expenses row and a balanced journal entry (Dr the category's expense account / Cr Cash or Bank). Also reachable via a cash-drawer expense on /admin/registers (see Cash movement).

Manual voucher (journal / payment / receipt / contra) — /admin/accounting (Vouchers tabs)

• Purpose: Post manual double-entry that the automated flows don't generate — owner capital, bank charges, depreciation, accruals, reclassifications, opening balances.
• Access: create / edit / view / delete = FINANCE_ROLES; approve / post / reverse = MANAGERS (owner/admin/manager). Backend: createVoucher / updateVoucher / approveVoucher / postVoucher / reverseVoucher (src/lib/vouchers.functions.ts → vouchers.server.ts) → vouchers + voucher_lines; posting writes journal_entries / journal_entry_lines.

Header fields

Line grid (voucher_lines, min 2 rows)

Balanced-entry enforcement — the totals row shows "Out by ₨X" (amber) until debits = credits, then flips to "Balanced"; Save is disabled while unbalanced. validateLines re-checks on the server (and the assert_journal_balanced DB trigger on post): rejects <2 lines ("A voucher needs at least two lines."), a line with both debit and credit, and any imbalance ("Voucher is not balanced…"). Type-specific rules: payment = exactly one Cash/Bank line, credited; receipt = exactly one Cash/Bank line, debited; contra = exactly two Cash/Bank lines (different accounts), one debit + one credit.

Lifecycle — draft → approved → posted → reversed. Save draft creates the voucher with no ledger impact. Open it (View) → Approve (managers) → Post — only posting writes the journal entry and moves the trial balance. A posted voucher shows Reverse, which writes an equal-and-opposite (debits↔credits swapped) contra entry, period-guarded — never by editing the original. Delete is allowed only while draft.

Cross-form effects — posted vouchers appear in General Ledger / Trial Balance / P&L / Balance Sheet identically to automated postings; AUD voucher.* actions logged; department/cost-center dimensions feed the Departments and Cost Centers report tabs.

Chart of accounts — /admin/accounts

• Access: UI permission="accounting". Backend: saveMasterDataFn (entity accounts) → accounts.

Connections — journal_entry_lines.account_id, expense_categories.account_id, cash_accounts.account_id, self parent_id. System accounts (is_system) are protected from deletion; the default 14-line chart is provisioned at onboarding.

Expense category — /admin/expense-categories

• Access: UI permission="accounting". Backend: saveMasterDataFn (entity expense_categories) → expense_categories.

Connections — selected on Record expense (category_id); each category maps to an accounts row via account_id.

Payment method — /admin/payments

• Access: UI permission="settings". Backend: saveMasterDataFn (entity payment_methods) → payment_methods.

Connections — codes are referenced by POS payments, supplier payments and expenses. (Note: storefront checkout uses a hardcoded cod/bank/card list, not this table.)

Financial reports (read-only) — /admin/accounting

Tabs computed from the double-entry ledger (journal_entries / journal_entry_lines), not from UI sales totals. Shared filters: From / To date range, Branch, and (Ledger tab) Account; a Print current report button.

A ledger-integrity banner (getBalanceValidation) warns if total debits ≠ total credits in the range.

The same /admin/accounting page also hosts operational tabs beyond these read-only reports: Journal / Payment / Receipt / Contra Vouchers (see Manual voucher above), Fiscal Years / Periods (open/close periods — the posting guard that blocks back-dating into a closed month), Departments and Cost Centers (analytical dimensions tagged on voucher lines), and Bank Reconciliation (match statement lines against ledger cash/bank movements until the difference is zero).

Tables owned: suppliers (shop_id→shops), purchase_orders (shop_id→shops, supplier_id→suppliers; po_status; unique (shop_id, po_number)), purchase_order_items (purchase_order_id→purchase_orders, variant_id→product_variants), goods_receipts (purchase_order_id→purchase_orders, location_id→inventory_locations; unique (shop_id, receipt_number)), goods_receipt_items (goods_receipt_id→goods_receipts, variant_id→product_variants), supplier_invoices (supplier_id→suppliers, purchase_order_id→purchase_orders, goods_receipt_id→goods_receipts; payment_status), supplier_payments (supplier_invoice_id→supplier_invoices), accounts (self-FK parent_id; account_type; is_system), journal_entries (shop_id→shops, branch_id→branches), journal_entry_lines (journal_entry_id→journal_entries, account_id→accounts), expenses (category_id→expense_categories, branch_id→branches), expense_categories (account_id→accounts), payment_methods (shop_id→shops), bank_accounts (account_id→accounts).

Budgets — /admin/budgets

• Purpose: Annual budgets by account (optionally per month) with Budget vs Actual computed against the live ledger (posted actuals only).
• Access: view / edit draft lines = FINANCE_ROLES; Approve = owner/admin. Backend: createBudget / getBudget / upsertBudgetLine / setBudgetStatus / budgetVsActual (src/lib/finance-reports.functions.ts → finance-reports.server.ts) → budgets + budget_lines.

Create + line fields

Lines — added on the Budget lines tab while the budget is draft. Enter an account code + amount and press Add / update line: the code is resolved against the Chart of Accounts server-side and the line is upserted (re-entering the same code updates its amount instead of duplicating). Lines become read-only once the budget is approved.

Budget vs Actual — the second tab compares each budgeted account to its posted ledger actual (year-to-date): Budget, Actual, Variance and Variance %, with over-budget variance highlighted amber. (Procurement requisitions can reference a budget for encumbrance context.)

Lifecycle — draft → approved (Approve, owner/admin). Only draft budgets accept line edits.

Connections — budget_lines.account_id→accounts; budgets.fiscal_year_id→fiscal_years (optional); actuals read from posted journal_entry_lines.

Receivables & Payables (ageing statements) — /admin/receivables, /admin/payables

• Purpose: Read-only ageing of customer (AR) and supplier (AP) outstanding balances, bucketed Current / 1–30 / 31–60 / 61–90 / 90+ as of a chosen date. Click a row to open that party's running statement (opening balance → dated debits/credits → closing balance).
• Access: FINANCE_ROLES. Backend: getArAgeing / getApAgeing + per-party statement (finance-reports.server.ts), derived from sales & their tenders (AR — cash sales excluded) and supplier_invoices / supplier_payments (AP).
• Settlement is done elsewhere — these pages are read-only. Clear an AR balance from Sales → Record payment on the sale; clear an AP balance from Purchasing → Record a payment on the supplier invoice. The balance drops to zero once the settling payment posts (Dr Bank/Cash · Cr Accounts Receivable, or Dr Accounts Payable · Cr Bank/Cash), and the trial balance stays balanced.

Sales — POS, Registers, Orders & Sync

POS sale (cart) — /admin/pos

• Purpose: Build a retail cart (scan/tap products, per-line and order discounts, attach customer, hold/resume) and start checkout.
• Access: SELLING_ROLES = owner, admin, manager, cashier (enforced by posCheckout).
• Backend: posCheckout (src/lib/pos.functions.ts) → recordPosSale (src/lib/pos.server.ts) → record_pos_sale RPC → orders, order_items, payments, receipts, inventory_movements/inventory_balances, journal_entries, cash_movements.

Order-level fields

Cart lines (UI Line; server posLine)

Offline snapshot (sent only on offline queue / sync retry — client_snapshot): device_id (text ≤80, marks orders.is_offline), local_seq (int), offline_created_at (ISO), and immutable client_snapshot.{lines, subtotal, discount_total, tax_total, total} — the "as-charged" record the server reconciles against; variance → pos_sync_conflicts.

Keyboard shortcuts: F2 Search · F4 Customer · F6 Order discount · F8 Hold · F9 Pay · Esc Cancel/close (↑/↓/←/→ move the grid highlight; Enter in search adds the highlighted item). Hold/Resume held sales are client-only state (no backend).

Connections

• Selects / references: Variant/Product (catalog + inventory_balances), Customer (customer_id), Register (register_id); open cash_sessions resolved server-side.
• Feeds / used by: completed sale → order_items, payments, inventory_movements, receipts, journal_entries (Dr Cash 1000/Bank 1100; Cr Revenue 4000 + Tax 2100; Dr COGS 5000 / Cr Inventory 1200), cash_movements; low-stock → ai_alerts.
• Cross-form effects: server is the pricing authority (recomputes via priceCart); payment total must equal order total within currency tolerance; duplicate local_uuid returns the existing order; offline/failed sales queue to /admin/sync.

Payment screen — /admin/pos (Pay modal, F9)

• Purpose: Allocate split payments across methods and compute change, then complete the sale.
• Access: SELLING_ROLES. Backend: same as POS Sale → payments (+ cash_movements for cash).

Split-payment rows (UI PaymentRow; server payments[])

≥1 payment required; "Split payment" adds a row prefilled with the remaining. Complete is enabled only when fully allocated (allocated ≥ subtotal, some amount >0, subtotal >0).

Credit (pay later) — udhaar. When Settings → Customers & credit has credit sales on and the signed-in user's role is permitted (credit_roles), the Pay screen shows a Credit sale (udhaar / pay later) toggle. With it ticked the button becomes Complete credit sale and the sale can post with partial or zero tender — the unpaid remainder is booked to the customer's account (Accounts Receivable) and the order is marked partial or unpaid.

• A customer is required — a credit sale can't complete as a guest (you're prompted to attach one first).
• The customer's credit limit is enforced: their existing outstanding balance + this sale must stay within their credit_limit (0 = unlimited). A manager sees an Override the customer's credit limit checkbox to push past it.
• Credit sales are online-only — they're server-validated and are never queued offline. Settle the balance later via Sales → Record payment.

Open cash session — /admin/pos header & /admin/registers

• Purpose: Open a register drawer with an opening float.
• Access: any active member; non-managers must be assigned to the register.
• Backend: openCashSession (src/lib/cash.functions.ts) → cash_sessions + cash_movements (opening).

Cash movement (in/out/expense) — /admin/registers (session panel)

• Purpose: Record cash added to / removed from an open drawer, or a cash expense.
• Access: any active member; UI enables only for managers or the assigned opener.
• Backend: recordCashMovement (cash.functions.ts) → cash_movements (+ recordExpenseAndPost → expense + journal_entries when type=expense).

Close cash session — /admin/pos header & /admin/registers

• Purpose: Count the drawer and close the session, computing variance vs expected.
• Access: any member; only the opener or a manager may close.
• Backend: closeCashSession (cash.functions.ts) → cash_sessions update + cash_movements (closing) + ai_alerts (on discrepancy).

Read-only reconciliation stats: Opening, Cash sales, Refunds, Cash in, Cash out, Expenses, Expected, Counted, Difference.

Register create / edit / assign — /admin/registers

• Access: MANAGERS = owner, admin, manager. Backend: createRegister / updateRegister / assignRegisterUser / unassignRegisterUser (cash.functions.ts) → registers, register_users.

Create/edit

Assign users — per-member checkbox writes register_users (registerId + userId, idempotent, unique (register_id,user_id)).

Connections (registers) — references Register (register_id), Branch (branch_id), staff from shop_users, session (cash_session_id). An open register session gates POS selling; movements + sessions feed reconciliation and journal entries; discrepancies raise ai_alerts. One open session per register; refunds land back in the originating open session's drawer.

Return / refund — /admin/orders (order detail)

• Purpose: Return order lines, optionally restock, and issue a refund.
• Access: MANAGERS (refunds move money out).
• Backend: posRefund (pos.functions.ts) → recordReturn → record_pos_return RPC → returns, return_items, refunds, inventory_movements (restock), journal_entries (reversing), cash_movements, orders status.

Header fields

Return lines (server items[])

The admin.orders.tsx Return items modal surfaces per-line return quantity (partial returns), a Reason dropdown, a Refund method selector, and a Restock returned items toggle; the live Refund ≈ estimate updates as you set quantities, and Confirm return posts the reversing entry. Verified example: a partial return of one line on a ₨16,399 sale created RET-000001 (₨3,499 refund), set the order payment status to partial, restocked the unit, and reduced Revenue −₨3,499 + COGS −₨1,800 in the ledger (still balanced; A = L + E holds).

Sales — list & detail — /admin/sales

• Purpose: Browse every counter / online / AI sale in one place, open a sale for full detail, and record a payment to settle a credit/partial balance.
• Access: view a sale's detail = owner, admin, manager, cashier, accountant (getSaleDetail); Record payment = owner, admin, manager, accountant (recordSalePayment).
• Backend: list via a direct orders read; detail via getSaleDetail; payment via recordSalePayment (src/lib/orders.functions.ts) → record_order_payment RPC → payments (+ updates orders.paid_total/payment_status).

List filters

Each row shows Sale # · Date · Channel · Customer · Payment · Total · Outstanding (Total − Paid). View opens a read-only detail modal: line items (qty / unit / discount / tax / total), the subtotal → discount → tax → shipping → Total breakdown, Paid vs Outstanding, the tenders (payments), plus customer, register, cashier and any returns.

Record payment — shown in the detail modal only while a sale still has an outstanding balance (a credit / partial sale):

Recording a payment increments paid_total, moves the sale to partial / paid, and adds a tender row — the same settlement path used to clear udhaar balances taken at the till.

Offline sync — queue & conflict resolution — /admin/sync

• Purpose: Retry queued offline sales and resolve server-side price/tax/rejected conflicts (accept / reject / retry).
• Access: viewing = any member; resolve/discard/retry = owner, admin, manager (DESTRUCTIVE_ROLES).
• Backend: syncOfflineSales (pos.functions.ts, batch ≤50); listSyncConflicts / resolveSyncConflict (sync.functions.ts) → pos_sync_conflicts (+ recordPosSale on retry of rejected).

Conflict resolution fields

Local device queue ("On this device" / "Rejected on this device", IndexedDB via src/lib/offline, not a DB table): Retry resends the PendingSale payload (incl. device_id, local_seq, offline_created_at, client_snapshot) via syncOfflineSales; Discard (manager-only) drops the local pending sale/conflict.

Connections

• Selects / references: conflicts reference register_id, branch_id, device_id, local_uuid, cashier_id; payload holds the original sale + snapshot, server_state holds the server re-price.
• Feeds / used by: retrying a rejected conflict/queued sale calls record_pos_sale (idempotent on local_uuid); variance conflicts already have a posted order and only log the variance.
• Cross-form effects: every offline sale failing validation is recorded as a rejected conflict rather than lost; the server never overwrites a posted order — it honours the as-charged snapshot and records the difference here.

Tables owned: orders (FKs shop_id→shops, branch_id→branches, register_id→registers, cash_session_id→cash_sessions, customer_id→customers; unique (shop_id, order_number), partial-unique (shop_id, local_uuid)), order_items (order_id→orders, variant_id→product_variants), payments (order_id→orders), receipts (order_id→orders; unique (shop_id, receipt_number)), returns (order_id→orders; unique (shop_id, return_number)), return_items (return_id→returns, order_item_id→order_items, variant_id→product_variants), refunds (order_id→orders, return_id→returns), registers (branch_id→branches), register_users (register_id→registers; unique (register_id, user_id)), cash_sessions (register_id→registers), cash_movements (cash_session_id→cash_sessions, register_id→registers; type sale/refund/expense/cash_in/cash_out/opening/closing), cash_accounts (account_id→accounts), pos_sync_conflicts (branch_id→branches, register_id→registers; unique (shop_id, local_uuid)).

Storefront Editor & AI (Admin)

All Storefront Editor forms load via getAdminStorefrontFn → getAdminStorefront (src/lib/storefront-admin.server.ts), returning { shop, settings, banners, sections, navigation, policies, pages, themes } for the active shop. All writes require owner / admin / manager (assertManager). The editor is a single route with tabs (theme, banners, sections, navigation, pages, policies, contact, domains) plus an opt-in live-preview iframe of /store/<slug>?preview=1.

Draft vs Publish model:

• Theme tab writes go into storefront_settings.draft (a JSON blob) via saveSettingsDraftFn and never touch live columns until publish.
• Banners / Sections / Navigation rows are written with is_draft = true on every save.
• Publish (publishStorefrontFn): copies each key in SETTINGS_DRAFT_KEYS from draft into live columns, sets is_published = true, clears draft = {}, and flips is_draft = false on all draft banner/section/nav rows.
• Discard draft (discardStorefrontDraftFn): clears draft = {} and deletes banner/section/nav rows still is_draft = true.
• Pages, Policies, Contact/Branding write straight to live (no draft staging); Pages/Policies have their own is_published flag.

Theme — /admin/storefront (tab: Theme)

• Purpose: Colours, layout variant, font, hero, announcement bar, social links, SEO meta.
• Backend: saveSettingsDraftFn (src/lib/storefront-admin.functions.ts) → storefront_settings.draft (JSON merge). "Reset to theme default" calls the same fn with only colour/font keys.

Saved as one draft patch. Colour fields initialise from the theme's own palette when the shop hasn't genuinely customised them (customColor / THEME_DEFAULT_SETTINGS, src/lib/storefront-theme.ts).

Reset to theme default patches the five colours + font_family to THEME_DEFAULT_SETTINGS, leaving hero/announcement/social/SEO untouched. Still requires Publish. Persisted draft keys (SETTINGS_DRAFT_KEYS): homepage_variant, primary/secondary/accent/text/background_color, font_family, announcement_bar, header, footer, hero, social_links, seo, theme_code (header/footer/theme_code are draftable but not in this UI).

Banners — /admin/storefront (tab: Banners)

• Backend: saveBannerFn / deleteBannerFn → storefront_banners. Every save sets is_draft = true.

Sections — /admin/storefront (tab: Sections)

• Backend: saveSectionFn / deleteSectionFn → storefront_sections. Save sets is_draft = true.

Navigation — /admin/storefront (tab: Navigation)

• Backend: saveNavItemFn / deleteNavItemFn → storefront_navigation. Save sets is_draft = true.

Pages — /admin/storefront (tab: Pages)

• Backend: savePageFn / deletePageFn → storefront_pages (live, no draft staging).

Policies — /admin/storefront (tab: Policies)

• Backend: savePolicyFn → storefront_policies (upsert on shop_id, policy_type, live).

POLICY_TYPES titles: Privacy Policy, Terms & Conditions, Return Policy, Shipping Policy, FAQ.

Branding & Contact — /admin/storefront (tab: Contact)

• Backend: saveContactInfoFn → shops table (not a storefront_* table). Written live.

Storefront Connections

• Selects / references: Sections/banners reference categories & products (via config JSON / links); Navigation URLs point at storefront customer pages; Pages & Policies render as customer info pages.
• Feeds / used by: all published rows drive the public storefront at /store/<shop.slug>; seo feeds meta tags; theme colours/font inject storefront CSS; branding feeds header + receipts. Public reads are RLS-gated to is_visible AND NOT is_draft.
• Cross-form effects: Theme + banner/section/nav changes stay hidden until Publish; currency/language/timezone are managed in /admin/settings, not here.

Domains (connect your own domain) — /admin/storefront (tab: Domains)

• Purpose: Connect your own domain(s) (e.g. trendies.pk) so your storefront is served at clean root URLs on your own brand — https://trendies.pk/, /product/<slug>, /cart, /checkout — with no /store/<slug>/ prefix. The original /store/<shopSlug>/* links keep working.
• Access: owner / admin only (requireRole(..., ADMINS)).
• Backend: listDomainsFn / addDomainFn / verifyDomainFn / setPrimaryDomainFn / removeDomainFn (src/lib/domains.functions.ts) → domains.server.ts → shop_domains table.

Merchant flow

1. Add the domain — Storefront → Domains, type the host, click Add domain (lists as Pending).
2. Create the DNS records at your registrar: an A record (@ → 185.158.133.1) plus the _lovable TXT verification record — use the exact values shown on screen.
3. The platform verifies ownership and issues the SSL certificate (the free https:// padlock).
4. Once the domain resolves to your store, click Mark verified — it switches to Verified and your storefront goes live on it.
5. (Optional) If you added more than one (e.g. apex + www), click Make primary; secondary domains redirect to the primary.
6. (Optional) Serves — each domain has a Serves selector (shown as soon as the domain is added, even before DNS verification) choosing WHAT it serves at its root: Online store (default — the storefront, as above) or Restaurant website (the /dine site from Restaurant → Website). A restaurant-assigned domain opens the restaurant site at / and is its own home — it is not redirected to the store's primary domain. Changing it saves immediately and is recorded in the audit log (shop_site.domain_assigned).

Unknown / unverified hosts never resolve to a shop, and one domain maps to exactly one shop. Full registrar-by-registrar steps (including Namecheap) are in the in-app guide at /admin/domain-setup.

AI (Admin) — /admin/ai

Three tabs: Assistant (chat + right-rail panels: reports, pending actions, action history, permissions, alerts), Knowledge base, Business memory. Most AI writes require owner / admin / manager; chat itself only needs active shop membership.

Assistant chat — /admin/ai (tab: Assistant)

• Backend: askAssistant (src/lib/ai.functions.ts) → aiChat (agent "assistant") → ai_conversations, ai_messages, ai_tool_calls, may insert ai_action_approvals.

Reports: Morning briefing (getBriefing) and End-of-day summary (getEndOfDay), input {shopId} only.

The assistant can take actions, not just answer. Ask it to create a purchase order, adjust inventory, record an expense or payment, or draft a message; it resolves the records it needs (supplier, product, amounts) and then either runs immediately or queues for approval depending on that capability's mode in AI permissions (disabled / approval / automatic). Approval-mode actions appear under Pending AI actions; on Approve the action is actually executed and its result is posted back into the chat (see Permission matrix and Approval queue). Actions never exceed the acting user's role limits.

Permission matrix — /admin/ai ("AI permissions" panel)

• Purpose: Per-capability mode governing whether the AI may act.
• Backend: direct Supabase update on ai_permissions.mode; server-side action execution re-checks has_shop_role.

Seeded capabilities (one ai_permissions row per shop): salesman → view_products / view_inventory / view_prices / recommend_products / add_to_cart / track_order (automatic), create_order (approval). assistant → view_sales / view_inventory / view_purchases / view_expenses / view_accounting / view_customers / suggest_reorders / generate_reports (automatic), create_purchase_order / adjust_inventory / record_expense / issue_refund (approval).

Approval queue — /admin/ai (Pending AI actions / Action history)

• Backend: read ai_action_approvals (limit 30, newest first); decide via decideAiApproval → on approve runs executeAiAction, writes result back, posts an ai_messages summary.

Row display fields: action, payload (summarised: supplier, items, total, amount, quantity, variant, reason, note), status (approval_status: pending/approved/rejected/executed, plus app-written failed), created_at, executed_at, result, error, requested_by, decided_by, decided_at, conversation_id.

Alerts — /admin/ai ("Alerts" panel)

• Backend: listAlerts / refreshAlerts (src/lib/ai-insights.functions.ts) → ai_alerts. Dismiss = direct update is_read=true. Columns: alert_type, severity (info/warning/critical), title, message, data (JSON), is_read, created_at.

Knowledge base — /admin/ai (tab: Knowledge base)

• Backend: addKnowledgeDocumentFn / listKnowledgeDocumentsFn / deleteKnowledgeDocumentFn → ai_knowledge_documents (+ chunks into ai_knowledge_chunks).

content is split by chunkText (~800 chars, 120 overlap) into ai_knowledge_chunks (each with a generated search tsvector). Returns {documentId, chunkCount}. List row shows title, chunk_count (auto), source, created_at.

Business memory — /admin/ai (tab: Business memory)

• Backend: listBusinessMemoryFn / createBusinessMemoryFn / updateBusinessMemoryFn / setBusinessMemoryActiveFn / decideBusinessMemoryFn (src/lib/ai-memory.functions.ts) → ai_business_memory.

Add memory

Edit id + scope?/content?. Toggle active id + isActive. Decide AI-proposed id + decision (approved\|rejected) — only affects source='ai' AND status='pending'; approve also sets is_active=true. The UI splits into AI-proposed (pending → Approve/Reject) and Approved (Edit / Activate-Deactivate). AI reads (activeBusinessMemory) only include is_active=true AND status='approved'.

AI Connections

• Permissions gate actions: a capability's mode decides disabled (blocked) / approval (queued into ai_action_approvals) / automatic (executed). Approve re-verifies role + mode server-side before executeAiAction.
• Knowledge → chunks: documents are chunked into ai_knowledge_chunks, retrieved by shop-scoped full-text to ground chat answers.
• Memory needs approval: AI-proposed memory stays pending/inactive until a manager approves.
• Conversations/messages/tool-calls record the chat; approval decisions post follow-up ai_messages.

Tables owned:

• Storefront: storefront_settings (unique shop_id; live cols + draft jsonb; theme_code default zenis), storefront_themes (global, variants jsonb, no shop FK), storefront_pages (unique (shop_id, slug)), storefront_sections (is_draft), storefront_navigation (self-FK parent_id; is_draft), storefront_banners (is_draft), storefront_policies (unique (shop_id, policy_type)). Branding/Contact writes target shops.
• AI: ai_permissions (unique (shop_id, agent, capability); agent=ai_agent), ai_conversations (customer_id→customers), ai_messages (conversation_id→ai_conversations), ai_tool_calls (conversation_id→ai_conversations), ai_action_approvals (conversation_id→ai_conversations; status=approval_status), ai_knowledge_documents, ai_knowledge_chunks (document_id→ai_knowledge_documents; generated search tsvector), ai_alerts, ai_business_memory (scope/source/status/confidence/is_active; RLS owner/admin/manager).

Storefront — Customer Forms

Auth pages (sign in / up / forgot) call Supabase Auth directly from the browser (supabase.auth.*), not a server fn. Cart, wishlist, and compare are client-only, persisted in localStorage (zenis-store:<shopSlug>) via useStorefrontCart (src/lib/cart-store.ts); the DB carts / cart_items / wishlists tables are not written by any storefront route. A customers row is created lazily on first authenticated account/checkout access (getOrCreateCustomer), or by placeOnlineOrder for guests.

Customer sign in — /store/$shopSlug/sign-in

• Purpose: Authenticate a returning shop-scoped customer (password or Google OAuth).
• Access: guest (redirects to account if already signed in).
• Backend: supabase.auth.signInWithPassword / OAuth google / supabase.auth.resend → auth.users.

Connections — on success navigates to account; session drives getCustomerAccount/checkout prefill; account is scoped per shop (metadata shop_slug).

Customer sign up — /store/$shopSlug/sign-up

• Access: guest. Backend: supabase.auth.signUp / OAuth google → auth.users; app customers row created later, lazily.

Connections — confirmed session → account; later getOrCreateCustomer inserts customers (shop_id, user_id, email). Duplicate-email surfaced as "already exists".

Forgot password — /store/$shopSlug/forgot-password

• Access: guest. Backend: supabase.auth.resetPasswordForEmail → email; redirects to shared /reset-password?next=<account>.

Product page — add to cart — /store/$shopSlug/product/$slug

• Purpose: Choose a variant + quantity and add to cart (or wishlist/compare).
• Access: guest or signed-in. Backend: none on add (localStorage addToCart/toggleList); page data via getStorefrontProduct. No review form exists.