Kuberan Grocery Operating System

1. Purpose and product boundaries

Kuberan is a local-first grocery operating system, not only a cash register. It connects checkout, stock, purchasing, staff, customers, cash, banking, tax and store administration while keeping each role’s screen simple.

Version 1 decisions

• Flutter applications use a local SQLite database so essential work continues without the network.
• The store box runs Java/Spring Boot and SQLite. Clients call Java APIs and never open the server database file.
• The store box is the local authority. A future cloud layer may support multi-store operations without becoming necessary for a single store to trade.
• Inventory uses an append-only movement ledger with a derived quantity-on-hand value.
• AI assists with reading, matching, forecasting and explanation. It does not own transaction integrity, payment approval, tax filing or silent posting.

2. The application family

Why separate apps? A cashier should not navigate accounting, and an accountant should not see lane controls. Shared Flutter packages can still provide one design system, identity, API client, sync engine and database foundation.

3. People, roles and permissions

Permission principles

• Deny by default; grant the smallest practical job permission.
• Separate “view,” “draft,” “approve,” “post,” “pay,” “export” and “administer.”
• Currency limits and reason codes apply to refunds, voids, discounts, price overrides, cash movement and store credit.
• High-risk actions require fresh authentication and cannot rely on an old offline session forever.
• Every approval records who, when, device, reason, previous value and resulting event.

4. Installing the Kuberan Store Box

Follow along in the Store Box Setup prototype.

1. Place and power the box.

   Use a ventilated, secure location near the network equipment and UPS. Do not place it under a sink, near heat, or where staff can unplug it for another device.

2. Connect wired Ethernet.

   Connect the primary network port to the business router or managed switch. Registers may use Wi‑Fi; the box should be wired.

3. Open the setup address.

   From a device on the same network, open the printed local setup address. The first-run certificate and box identity are verified using the code on the sealed card.

4. Create the owner administrator.

   Use a unique long password, enable a second factor where available, print/store recovery codes away from the box, and add a second trusted owner.

5. Pair devices.

   Install the signed Kuberan client, enter the one-time code, assign the device’s role and location, then allow initial data download to complete.

6. Test hardware and backups.

   Run scanner, printer, drawer, scale, display and payment tests. Attach encrypted backup storage and confirm an off-site destination if used.

5. Initial store configuration

Store and receipt

• Legal and operating name, address, phone, HST registration number and store number.
• Receipt header/footer, return policy, loyalty text and accessibility/contact information.
• Business day boundary, timezone, currency, rounding and fiscal calendar.

Departments and locations

• Grocery, produce, meat, seafood, deli, bakery, dairy, frozen, health/beauty, household and other local departments.
• Sales floor, receiving, backroom, coolers, freezers, prep areas, cash office, warehouse and waste locations.

Products and rules

• Product/SKU, UPC/EAN, PLU, vendor item, pack/case/unit conversions, variable weight and embedded-price barcodes.
• Cost, regular/member price, effective date, department, category, tax status, deposits/fees and return restrictions.
• Lot/expiry policy, minimum facing, reorder point, safety stock, lead time, preferred vendor and label template.

Import strategy

Import products into a staging area, validate duplicates and tax categories, test representative products at checkout, and publish a signed product/price snapshot to devices. Never import directly into live tables without a review report and rollback package.

6. Daily store opening

1. Review the manager opening card. Confirm box, devices, backup, payment connection, scales and critical alerts.
2. Open the cash office. Prepare numbered tills or floats using two-person verification if store policy requires it.
3. Start registers. Cashier signs in, confirms lane, counts/accepts float and performs a printer/terminal check.
4. Review deliveries and staffing. Confirm receiving windows, cold-chain coverage, call-outs and open shifts.
5. Walk exceptions. Out-of-stocks, price-sign mismatches, expired items, recalls, refrigeration alarms and safety checks become assigned tasks.

7. Checkout operations

Use the Checkout prototype to test scanning, offline mode, split tender and sale completion.

Normal sale

Checkout requirements

When the register says offline

Continue normal cash transactions. Product, price, tax and promotion data comes from the last signed local snapshot. Card acceptance depends on the payment terminal/processor connection and approved offline policy. Never tell a customer a card is approved unless the processor returned an approval or an approved store-and-forward mode is active.

8. Inventory and receiving

Use the Inventory prototype to receive the Dairyland order and simulate invoice scanning.

Receiving a planned PO

1. Choose/scan the PO and receiving location; record arrival and temperature/seal checks where relevant.
2. Scan cases/items and record actual accepted quantity, lot/expiry, cost and damage/shortage.
3. Compare ordered, shipped, received and invoiced quantities. Preserve supplier document images.
4. A permitted receiver posts one receipt, creating positive inventory movements by location.
5. Differences create a vendor claim or invoice-review task; they do not disappear into a corrected total.

Unplanned delivery

Create a blind receipt linked to the vendor, require a reason and elevated approval, then either create/associate a PO or explicitly approve the non-PO purchase. This avoids inventing ordered quantities after seeing the delivery.

Inventory movements

Sale, return, receipt, transfer, count adjustment, damage, waste, spoilage, recall hold, production/use and administrative correction are distinct reasoned movements. Quantity-on-hand is a projection of the ledger; corrections are new movements, never edits to history.

Counts and perishables

• Support blind counts, recount thresholds, cycle plans, full physical counts and location-by-location completion.
• Track lot/expiry only where operationally valuable, not as mandatory data for every grocery item.
• Use FEFO guidance, markdown suggestions, donation/waste disposition, traceability and recall quarantine.

9. Purchasing and vendor management

Review a suggested order in the Purchasing prototype.

Order suggestion inputs

On-hand and available stock, open purchase/transfer orders, recent sales, seasonality, promotion uplift, waste, safety stock, minimum presentation, lead time, delivery calendar, case pack, minimum order, budget and known events.

Approval flow

Vendor record

Legal name, contacts, remit address, tax ID where required, order method, terms, currency, delivery windows, catalogue versions, lead time, minimums, deposits, allowances, chargebacks, certificates, insurance, scorecards and active/inactive status.

10. Staff, scheduling and timesheets

Open the Staff & Time prototype and approve Priya’s timesheet.

Employee lifecycle

Hire/onboard, identity/contact, emergency contact, role, department, pay reference (not full payroll banking unless required), availability, skills, training, certifications, policy acknowledgement, status change and termination access removal.

Schedule

Create demand-informed shifts, verify skill/coverage, availability, rest and store policy, publish, notify, offer open shifts and record swaps/call-outs with manager approval. The scheduling helper drafts; the manager publishes.

Timekeeping

• Clock in/out, paid/unpaid breaks, location/device rules, missed-punch request and manager correction.
• Show employees their own recorded time and change history before approval.
• Freeze an approved pay period; later corrections become separately approved adjustments.
• Export to the chosen payroll provider with totals, earnings codes and an audit/control total.

11. Customers, loyalty and service

Explore profile and consent controls in the Customers prototype.

Core workflows

• Minimal enrollment with explicit consent by purpose and a guest option.
• Earn/redeem points, member pricing, targeted offers and household/account rules.
• Gift card issue/activate/reload/redeem/void, store credit ledger and fraud limits.
• Receipt lookup, service case, complaint, product quality issue and resolution.
• Customer access, correction, opt-out and deletion/anonymization request subject to retention obligations.

Do not expose full customer profiles at every register. Cashiers see the minimum required to identify the member and complete the transaction.

12. Cash office and tender settlement

Till lifecycle

• Cash in/out, no-sale drawer open, pickup, safe drop, loan/change, deposit bag and till transfer require reasons and permissions.
• Cashier count should be blind to expected cash until submitted.
• Variance thresholds determine automatic acceptance or supervisor investigation.
• Card, gift card and store-credit tenders reconcile to processor/ledger batches, not just register totals.
• Bank deposits group documented bags/drops with preparer, verifier, date and statement match.

13. Finance, receipts and bank reconciliation

Use the Finance prototype to import and approve a sample statement.

Bank statement import

1. Accept CSV/OFX/QFX first; PDF is supported through extraction but receives stronger review.
2. Preserve the original file, compute a cryptographic fingerprint, reject accidental duplicate import and record account/period.
3. Normalize lines without deleting original description, date, amount, balance and statement position.
4. Apply deterministic exact rules, then ranked suggestions using vendor, amount, date, invoice, PO, tender batch and prior approved patterns.
5. User approves matches or categories. Posting stores statement line, matched records, rule/model version, evidence and reviewer.

Vendor invoice and receipt AI

AI extracts document type, vendor, invoice number, dates, subtotal, HST, deposits, discounts, total, lines and confidence. Duplicate checks use vendor/invoice/amount/date plus file fingerprint. Three-way matching compares PO, receipt and invoice; tolerances are policy, not AI judgment.

Accounting integration boundary

Kuberan may maintain an operational subledger and export summarized/controlled entries to an accounting package. Full general-ledger, payroll and corporate-tax replacement should be a deliberate later decision. Version 1 should prioritize accurate store evidence, reconciliation and accountant-ready exports.

14. HST working report

Kuberan prepares a traceable working package from the POS tax ledger and approved purchase documents. It should separate taxable, zero-rated, exempt and out-of-scope activity; returns; discounts; deposits/fees; bad debts/adjustments; and input tax credit exceptions.

Quarter/period workflow

1. Lock the operational period after sales, returns and tender reconciliation.
2. Confirm HST collected ties to protected transaction/tax summaries.
3. Confirm input tax credits are based on approved evidence with valid tax amounts.
4. Review missing/uncertain tax documents, prior-period adjustments and exceptional transactions.
5. Generate accountant package: summary, detailed schedules, exceptions, source links and control totals.
6. Authorized accountant/owner reviews and records filing/payment reference; Kuberan does not auto-file in Version 1.

15. Daily closing and month-end

Daily close

• All registers closed or explained; suspended sales reviewed.
• Cashiers submit blind counts; pickups/safe totals reconcile.
• Payment terminal batches and gift/store-credit ledgers reconcile.
• Receiving differences, waste, high-risk overrides, returns and voids reviewed.
• Backup completed or a clear task is assigned; store can still close if internet backup is delayed but local protected backup must remain.

Month-end

• All bank accounts/statements imported through period end and reconciled.
• Card processor settlement timing differences documented.
• Cash deposit-in-transit and outstanding items reviewed.
• Vendor receipts/invoices approved; accrual/export policy applied.
• Inventory valuation method, count adjustments, shrink and negative inventory reviewed.
• Payroll/time export control totals accepted.
• HST working report and exceptions reviewed.
• Operational period locked; reopening requires owner/accountant authority and audit reason.

16. Offline and synchronization behaviour

Run the interactive outage in Offline Sync & Local AI.

What users see

• All caught up: device and server agree.
• Working offline: work is safe on this device; a count of queued actions is shown.
• Syncing: connection returned and queued actions are being acknowledged.
• Needs help: a permanent reject or device problem created a guided repair task. Other independent work continues.

Technical rule in plain language

The client saves the business record and an “event to send” together. The server remembers every event ID. If a response is lost and the client retries, the server returns the original result instead of making a duplicate sale. Clients download server changes in numbered order and remember the last number applied in the same local transaction.

Data ownership

Registers own completed sale events. The server owns product/price/tax policy. Inventory is an append-only movement ledger. Shared drafts use a version check and human merge. Balances such as store credit are ledgers with offline limits, never last-writer-wins fields.

17. Local AI and agent opportunities

Local AI runs on the store box when hardware allows. It works through an agent gateway and typed Java tools. It cannot directly write SQLite or bypass permissions.

Prohibited autonomous actions in Version 1

Card approval, payment to vendors, HST filing, silent journal posting, price/tax policy changes, employee discipline, refund/void approval and deletion of audit evidence.

AI evidence record

Keep model/workflow version, prompt/template, retrieved source IDs, timestamps, output, confidence, tool calls, user edits and final approval for consequential suggestions. Treat text inside vendor documents as untrusted data, not instructions to the agent.

18. Security, privacy and audit

• Encrypt network traffic on the store LAN; pair devices with one-time codes and device certificates.
• Encrypt sensitive local data/backup media as supported; protect OS accounts and restrict physical access to the box.
• Use role permissions, currency limits, fresh authentication, automatic lock and staff offboarding.
• Never store raw payment card data; use processor tokens/references and certified terminal integrations.
• Redact sensitive data from routine logs/support bundles.
• Audit master-data change, privileged view, export, approval, configuration, remote-support session and recovery action.
• Define Canadian/Ontario privacy notices, consent, access/correction, retention and breach response with counsel.

19. Backup, restore and business continuity

Backup layers

• Frequent local database-safe snapshots/continuous protected copies.
• Nightly encrypted removable/local backup, rotated so ransomware or operator error cannot destroy every copy.
• Encrypted off-site copy when internet is available, with retention appropriate to the business.
• Configuration, certificates/keys, attachments and model/workflow metadata included or separately recoverable.

Verification

A copied file is not a successful backup. Kuberan automatically restores into an isolated test area, runs SQLite integrity and application consistency checks, and reports the last verified recovery point.

Recovery runbook

1. Keep registers trading locally where safe and record the incident start.
2. Do not repeatedly power-cycle or replace drives without support guidance.
3. Choose the newest verified recovery point and restore to replacement/repaired hardware.
4. Re-establish the store identity and device trust. Devices upload locally committed events beyond the restored server cursor.
5. Run reconciliation for sales, inventory, cash and sequence continuity before declaring recovery complete.

20. Troubleshooting for store staff

21. Product scope checklist

This catalogue makes omissions visible. Items marked “later” should be deliberate releases, not forgotten workflows.

22. Recommended delivery roadmap

Phase 0 — Decisions and test harness

Confirm workflows, device matrix, payment provider, tax/accounting boundaries, product migration and pilot store. Create event-contract, sync chaos, hardware simulator and data-integrity tests.

Phase 1 — Reliable trade

Identity, store box, device pairing, product/price/tax snapshot, checkout, cash, returns, receipts, client outbox/server inbox/pull log, monitoring and backup/recovery.

Phase 2 — Stock and buying

Inventory ledger, receiving, counts, waste/expiry, transfers, vendors, POs, cost/invoice documents and label printing.

Phase 3 — People, manager and customer

Manager priorities/approvals, staff/time, labour, loyalty/gift/store credit, cases, store operations and reports.

Phase 4 — Finance and local AI

Bank import/reconciliation, tender/deposit matching, HST working package, accountant exports, document AI, local search and explanation. Add forecasting/anomaly agents after data quality is proven.

Pilot and rollout

Run shadow totals beside the existing system, controlled lanes/departments, failure drills, staff training, reconciliation sign-off, rollback plan and a minimum stable period before whole-store cutover.

23. Technical appendix

Store architecture

Required server data structures

• sync_inbox: event_id unique, device, hash, received time, result/server sequence.
• sync_change_log: monotonically increasing server_sequence, entity/event metadata and device-scope payload.
• device_cursor: device and last acknowledged/applied sequence, health and schema/app versions.
• business ledgers: sale/tender, inventory movement, points/store credit, cash/till and accounting evidence.
• outbox on clients: event ID, aggregate, type/version, base version, payload/hash, state, retry and error.

SQLite discipline through Version 5.x

Every client, store server and Kuberan-operated cloud service uses SQLite through at least Version 5.x. Use WAL mode, foreign keys, busy timeout, short transactions, indexed sync/status fields, one controlled writer model, integrity checks, bounded attachments outside the main database where appropriate, disk-space alarms, tested online backup and rehearsed restore. Repository interfaces exist for module clarity, testing and SQLite-specific optimization—not to maintain a second database implementation.

Event and API rules

• Globally unique IDs generated at origin; event schema is versioned and backward compatible through a supported window.
• Use idempotency for every externally retryable command, including payment/tender callbacks.
• Business corrections are explicit reversing/adjusting events; do not rewrite completed history.
• Snapshots have manifest/version/hash and are applied atomically before the device cursor becomes current.
• Money uses integer minor units or fixed decimal policy; quantity supports configured precision; timestamps store UTC plus business/local context.

Database horizon

No alternative database, dual-database adapter or database cutover is planned through Version 5.x. Capacity work must first optimize and, when necessary, operationally partition SQLite deployments. Any database change after Version 5 requires fresh benchmarks, a new architecture decision, a separately approved roadmap and a controlled migration plan; it is not assumed by the current product.