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>/…, demo trendies-store).

How to read this manual

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.

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

• 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."

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).
• 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 → 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

Pricing & discounts — settings section pricing

Purchasing — settings section purchasing

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).

Catalog

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: pick an existing attribute (EntitySelect attributes) or create inline (ensureAttributeFn → product_attributes + product_attribute_values); tick 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.

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), Storefront (status=active only), Inventory (balances/movements), Purchasing, Labels.
• Cross-form effects: opening stock → inventory_movements(opening)+inventory_balances; cost → variant_costs (private); price → product_variants.price (fires pricing_version trigger); sale price → prices; barcode → barcodes.

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. Inline creation from builder uses 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.

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.

Connections

• Selects / references: Location via location_id; items via variant_id; scope via categories.
• Feeds / used by: approved variances update inventory_balances; audit stock_count.approved.
• Cross-form effects: posting a count writes inventory_movements (type count) + updates inventory_balances for each non-zero variance.

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 for one product line against a supplier.
• 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).

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

Connections — references Supplier (supplier_id) and Variant (variant_id); 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.

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 AP journal entry), 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).

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.

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).

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).

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 current admin.orders.tsx UI only offers "Full return & refund" (all lines, full qty, restock=true, cash). Partial qty / restock toggle / method exist in the schema but aren't surfaced.

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) 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.

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.

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.

CartLine written per add: variant_id, quantity, name (product + variant), sku, price, image (first product image), product_slug.

Connections — reads Product / active Variant (price, compare_at_price, track_inventory, stock); cart/checkout/wishlist/compare read the same localStorage store; stock drives disabled state.

Cart — /store/$shopSlug/cart

• Access: guest or signed-in (client-side). Backend: none — localStorage. No coupon field.

Totals: Subtotal (auto, Σ price×qty client-side); note "Taxes and totals calculated securely at checkout". "Checkout" → checkout, which re-prices server-side.

Checkout — /store/$shopSlug/checkout

• Purpose: Capture contact + address + payment method and place an online order.
• Access: guest or signed-in (prefills name/email from session).
• Backend: quoteCart (prices, strips cost) and placeOnlineOrder (src/lib/checkout.functions.ts) → RPC record_pos_sale → orders, order_items, payments, receipts, inventory + journal; also customers, ai_alerts.

Contact / Billing details

Shipping address sub-form (shipping_address, all optional, stored as JSON on order): line1 (max 200), city (max 80), postal_code (max 30), country (max 80).

Payment / meta

Order summary (auto, from quoteCart): subtotal, tax_total, total, discount_total, and generated order_number / receipt_number.

Connections

• Selects / references: cart line items → Variants; payment method (hardcoded list, not from payment_methods table).
• Feeds / used by: creates orders (channel online, status confirmed), order_items, payments (non-COD), receipts, decrements inventory, posts journal, ai_alerts (new_order) — the same orders/order_items the admin Orders form reads; customers reused or inserted.
• Cross-form effects: on success clears cart, navigates to payment/success?order=<number>; per-IP rate limit (10/min); idempotent on client_uuid.

Track order — /store/$shopSlug/track-order

• Access: guest (public). Backend: trackOrder (src/lib/storefront.functions.ts) → reads orders + order_items (contact fields stripped from response).

Returns status/payment/fulfillment/tracking + items + total (read-only).

Account — Profile — /store/$shopSlug/account (tab: Profile)

• Access: signed-in customer. Backend: updateCustomerProfile (src/lib/customer.functions.ts) → customers.

Account — Addresses — /store/$shopSlug/account (tab: Addresses)

• Access: signed-in customer. Backend: upsertCustomerAddress / deleteCustomerAddress / setDefaultCustomerAddress → customer_addresses.

Address sub-form

Connections — saved addresses are the customer's own list (not auto-injected into the checkout form, which has its own inline fields).

Account — Order history / reorder — /store/$shopSlug/account (tab: Orders)

• Access: signed-in customer. Backend: getCustomerAccount + getOrderDetail → orders, order_items (scoped to own customer_id). Reorder is client-side (addToCart).

Read-only list: Order # / Date / Status / Payment / Total (from orders); View opens the detail modal; Reorder these items re-adds each order_item (with variant_id) to the cart.

Wishlist / Compare — /store/$shopSlug/wishlist · /compare

• Access: guest or signed-in (client-side). Backend: none — localStorage wishlist/compare lists (toggleList, addToCart). DB wishlists table is not used by the storefront. Each item shows stored name/sku/price/image with Add-to-cart and Remove buttons; Compare shows a Product / SKU / Price table.

Contact — /store/$shopSlug/contact

• Access: guest. No submit form — display-only contact links (address/phone/email/WhatsApp), directing users to the AI chat button. (vendor.tsx is likewise a display-only store profile.)

Tables owned: customers (shop_id→shops, user_id→auth.users, unique (shop_id,user_id)), customer_addresses (customer_id→customers), orders (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)). Defined but unused by these storefront routes (client-side localStorage instead): carts, cart_items, wishlists. Checkout payment methods are hardcoded (cod/bank/card), not from payment_methods. No product-review table/form exists.

Appendix A — Enumerations

Many forms share these fixed choice lists (defined as Postgres enum types). Where a form has a "status" or "type" select, it almost always draws from one of these:

Appendix B — Tables ↔ forms index

The database has ~75 tables, all scoped by shop_id. Key foreign keys (the wiring behind the "Connections" blocks):

Per-domain table ownership is listed at the end of each section above.