System Requirements Document for omni-pos

1. Introduction

Omni-POS Hybrid Ecosystem is a hybrid retail point-of-sale platform for Botswana shops, powered by Neo Systems Africa. It combines counter sales (cash and digital, including split payment and M-Pesa STK Push) with mobile AR product scanning, a shop-owner back office, and a superuser administration console. Every new account begins on a 3-Day Full Browsing Trial; payment of the P85.00 once-off account opening fee is required only at Item Checkout or at Trial Expiry.

The product serves four human roles — Admin (Superuser), Shop Owner, Cashier and Mobile Shopper — across a modular micro-frontend web surface (React + Vite), a React Native (Expo) mobile app for AR and camera work, and Go microservices for authentication, trial, payment and inventory. Six named AI assistants (Eliana, Caitlin, Alisha, Florence, Edmund, Neo) are part of the product's identity and are surfaced in onboarding and tuned from the Admin Web.

Omni-POS is a multi-tenant SaaS: a Shop Owner registers a shop by selecting one of three subscription tiers — Starter (P975/month), Pro (P1850/month) and Premium (P2850/month) — each carrying different options, and the Super Admin defines the tiers and the options inside each tier. Within the POS the Shop Owner runs promotions (terms and conditions apply), cashes out, runs end of day, generates GRVs, adds and edits stock items and edits prices, with promotion capability depending on the selected tier. The Mobile Shopper selects which shop to buy from, browses shelf categories with the items on those shelves, follows in-shop map directions to a product, scans items to read expiry dates, promotion prices and dates and prices, adds scanned items to cart, pays in the app without going to the cashier, and can buy remotely and choose when to collect; purchase history and reports show where each item was bought.

The build is delivered incrementally on https://www.lovable.dev under a CHANGELOG.md discipline: the changelog is read before any code is generated, only features not yet marked Stable are generated, completed features are never regenerated, and technical debt is tracked separately.

2. System Overview

Omni-POS is delivered as a multi-page SaaS ecosystem. Anonymous visitors meet a Landing surface, then a 2.5-second Splash Screen that routes by session state, then Onboarding, then AUTH. Authenticated users land in the surface that matches their role: Admin Web (superuser control, including the subscription tier catalogue), Shop Registration (tier selection and shop registration), Shop Owner Web (inventory, membership cards, sales reports, trial analytics), Inventory (stock items, prices, GRVs), Shop Operations (promotions, cash out, end of day), Cashier Web (hybrid sales), Shop Browse (shop selection and shelf categories), Shop Map (in-shop directions), User Mobile (AR scanning, cart, in-app payment, remote collection, trial status), or Order History (purchase history and reports).

Current delivery comprises:

• Frontend web: React + Vite micro-frontend modules for Landing, Splash Screen, Onboarding, AUTH, Admin Web, Shop Owner Web and Cashier Web; the admin dashboard uses React + Tailwind.
• Frontend mobile: React Native (Expo) for User Mobile, providing AR + camera.
• Backend: Go microservices — auth-service (FIDO2, Phone OTP, Payoneer OAuth, session management), trial-service (3-day counter, checkout blocker, P85 fee capture), payment-service (split payment, M-Pesa STK Push, Payoneer API), inventory-service (stock, AR product mapping, shelf categories, GRVs, price edits, promotions, cash out and end-of-day records).
• Provisioned infrastructure: a shared FastAPI backend process for application APIs and domain modules, a MariaDB database for application-owned persistent data, the React frontend, a LiteLLM gateway for the backend's model-provider calls, and a PostgreSQL instance supporting LiteLLM (separate from application-owned storage).
• External providers: M-Pesa (STK Push, callback at https://api.appforcestudio.com/neo/callback, BusinessShortCode NEOPOS) and Payoneer (OAuth and payments API).
• Deployment: Docker, with Kubernetes optional; callback URL base https://api.appforcestudio.com/neo; required environment variables MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET, PAYONEER_CLIENT_ID, AES_256_GCM_KEY.

Actors: Admin (Superuser), Shop Owner, Cashier, Mobile Shopper (human); M-Pesa, Payoneer, LiteLLM and the model providers (external/system). Access is role-restricted for Admin Web, Shop Registration, Shop Owner Web, Inventory, Shop Operations, Cashier Web, Shop Browse, Shop Map, User Mobile and Order History; Landing, Splash Screen, Onboarding and AUTH are anonymously reachable.

Narrow exclusions: no capabilities beyond those stated in the requirement thread are introduced; the CHANGELOG.md engine is a build-process obligation, not an end-user feature; Kubernetes is optional.

Removed from scope

• None — no concept from the authoritative requirement thread was removed or replaced.

2a. Product Interpretation and Delivery Boundary

Omni-POS is a first-party application with application-owned identity. Anonymous visitors can reach Landing, the Splash Screen, Onboarding and AUTH without an account. Identity is established at AUTH through one of three methods — Biometric, Phone (OTP) or Payoneer OAuth — with FIDO2 (WebAuthn) applied on all authentication pages. Once a session exists, the Splash Screen routes the user to the Dashboard; without a session it routes to Onboarding.

Role-restricted surfaces (Admin Web, Shop Registration, Shop Owner Web, Inventory, Shop Operations, Cashier Web, Shop Browse, Shop Map, User Mobile, Order History) are reached only after authentication and are scoped to the matching role: Admin (Superuser) controls the Admin Web; Shop Owner controls Shop Registration, Shop Owner Web, Inventory and Shop Operations; Cashier controls the Cashier Web; Mobile Shopper uses Shop Browse, Shop Map, User Mobile and Order History. The trial lifecycle is owned by trial-service: a new account starts a 3-day full browsing trial, may browse, add to cart and use AR during it, and payment of the P85.00 once-off account opening fee is required only at Item Checkout or at Trial Expiry.

Subscription tiers are owned by the Admin (Superuser): the Super Admin defines the three tiers — Starter (P975/month), Pro (P1850/month) and Premium (P2850/month) — and the options included in each tier. A Shop Owner registers a shop by selecting one tier and supplying shop name, location, logo, contact email and mobile numbers. Tier selection governs which POS options the shop can use, including promotion capability. Shop-level POS operations — promotions (terms and conditions apply), cash out, end of day, GRVs, adding and editing stock items, and editing prices — are owned by the Shop Owner within their own shop's data.

Mobile Shopper journeys are shop-scoped: the shopper selects which shop to buy from, browses shelf categories with the items on those shelves, follows in-shop map directions to a required product, scans items to read expiry dates, promotion prices and dates and prices, adds scanned items to cart, pays in the app without going to the cashier, and may buy remotely and choose a collection time when not physically in the shop. Purchase history and reports record where each item was bought.

Payment execution is owned by payment-service and the external gateways M-Pesa and Payoneer. M-Pesa STK Push is initiated by the backend and confirmed through the provider callback at https://api.appforcestudio.com/neo/callback; the Cashier observes the resulting payment state in the Cashier Web. Payoneer OAuth is a provider-owned authorization surface that returns the user to Omni-POS.

AI assistant responses are produced through the LiteLLM gateway, which the shared backend calls; LiteLLM's PostgreSQL store is infrastructure for the gateway and is not application-owned customer data. All application-owned persistent data lives in MariaDB and is encrypted at rest with AES-256-GCM; transactions follow PCI-DSS 4.0.

The CHANGELOG.md engine governs how the product is built, not what end users do: before generating any code the builder reads CHANGELOG.md, creates it if missing, generates only features not yet marked Stable, never regenerates completed features, appends a Date | Feature | Status entry after each build step, and tracks Technical Debt separately.

2c. Page Content and Component Coverage

Landing

• Information/state: anonymous public entry explaining Omni-POS, its hybrid sales and AR scanning, the four roles, the 3-Day Full Browsing Trial, the P85.00 once-off account opening fee, and the six AI assistants (Eliana, Caitlin, Alisha, Florence, Edmund, Neo). Tagline "Powered by; Neo Systems Africa!".
• Primary actions: enter the product (proceeds to Splash Screen / Onboarding); open AUTH.
• Supporting actions: read trial terms; view assistant roster.
• Domain entities: trial offer (3 days, P85.00), assistant roster, role descriptions.
• Component responsibilities: hero band with wordmark and price tag; ticker tape of sales states; role label tags; trial stamp; assistant label grid; entry controls.
• States: loading (static content, no blocking spinner); empty (not applicable — static marketing content); success (entry control routes onward); error (if session probe fails, entry still routes to Onboarding); recovery (retry entry).

Splash Screen

• Information/state: logo fade-in with "Neo Systems Africa" pulse; visible for 2.5s; session check result (session exists / no session).
• Primary actions: none required from the user; automatic routing.
• Supporting actions: none.
• Domain entities: session.
• Component responsibilities: logo animation, pulse text, session probe, router handoff.
• States: loading (2.5s animation and session check); empty (not applicable); success (session exists → Dashboard; no session → Onboarding); error (session probe failure → treated as no session → Onboarding); recovery (user can re-enter AUTH from Onboarding).

Onboarding

• Information/state: slider/video with three messages — "Welcome to Omni-POS", "Hybrid Sales + AR Scanning", and "AI Assistants: Eliana, Caitlin, Alisha, Florence, Edmund, Neo".
• Primary actions: advance slides; continue to AUTH.
• Supporting actions: skip to AUTH.
• Domain entities: onboarding slides, assistant roster.
• Component responsibilities: slide/video player, pagination, continue control.
• States: loading (media buffering indicator); empty (not applicable); success (advance/continue → AUTH); error (media fails → static slide text remains readable, continue still available); recovery (retry media or proceed).

AUTH

• Information/state: three authentication methods — Biometric, Phone (OTP), Payoneer OAuth — all under FIDO2 (WebAuthn). OTP entry state; provider redirect state.
• Primary actions: authenticate by Biometric; request and submit Phone OTP; start Payoneer OAuth.
• Supporting actions: resend OTP; switch method; return from provider.
• Domain entities: user identity, FIDO2 credential, OTP challenge, Payoneer OAuth grant, session.
• Component responsibilities: method selector, WebAuthn ceremony handler, OTP input and resend, OAuth redirect handler, session establishment.
• States: loading (ceremony/OTP in progress); empty (no method chosen); success (session established → role surface); error (invalid OTP, failed ceremony, denied OAuth → inline message and retry); recovery (resend OTP, retry biometric, restart OAuth).

Admin Web

• Information/state: superuser control surface with five areas — User management, System logs, Trial overrides, AI assistant tuning, Subscription tiers. Restricted to Admin (Superuser).
• Primary actions: manage users; read system logs; set trial overrides; tune AI assistants; define the three subscription tiers (Starter P975/month, Pro P1850/month, Premium P2850/month) and the options included in each tier.
• Supporting actions: filter logs; select assistant to tune; review override history; edit a tier's price and option set; review which shops are on which tier.
• Domain entities: user records, system log entries, trial override records, assistant tuning settings for Eliana, Caitlin, Alisha, Florence, Edmund, Neo, subscription tier definitions (name, monthly price, included options), shop-to-tier assignments.
• Component responsibilities: user table and actions, log viewer, override form, assistant tuning panel, subscription tier editor with per-tier option list and price field.
• States: loading (tables/panels fetching); empty (no logs / no overrides / no tiers defined yet); success (change saved with confirmation); error (save rejected → inline error, values retained); recovery (retry save).

Shop Registration

• Information/state: the three subscription tiers as offered by the Super Admin — Starter (P975/month), Pro (P1850/month), Premium (P2850/month) — each with its included options; shop registration fields: shop name, location, logo, contact email, contact mobile numbers. Restricted to Shop Owner.
• Primary actions: select a subscription tier; enter shop name, location, logo, contact email and mobile numbers; submit registration.
• Supporting actions: compare tier options; change the selected tier before submitting; replace the uploaded logo.
• Domain entities: subscription tier (name, monthly price, included options), shop (name, location, logo, contact email, contact mobile numbers, selected tier).
• Component responsibilities: tier comparison cards with monthly price and option list, shop details form, logo upload control, contact email and mobile number inputs, submit control with validation summary.
• States: loading (tier catalogue fetching); empty (no tiers published by the Super Admin → registration blocked with explanation); success (shop registered on the selected tier → Shop Owner Web); error (missing required field, invalid email or mobile number, tier unavailable → inline field errors with values retained); recovery (correct fields and resubmit).

Shop Owner Web

• Information/state: four areas — Inventory management, Membership cards, Sales reports, Trial analytics — plus the shop's current subscription tier and the options it unlocks. Restricted to Shop Owner.
• Primary actions: manage inventory; issue/manage membership cards; read sales reports; read trial analytics; view the shop's subscription tier and included options.
• Supporting actions: filter reports by period; search inventory; look up a membership card; open Inventory and Shop Operations from the overview.
• Domain entities: stock items, AR product mappings, membership cards, sales records, trial analytics data, shop subscription tier and included options.
• Component responsibilities: inventory table and editor, membership card manager, report charts/tables, trial analytics panel, subscription tier summary with included-option list.
• States: loading (data fetching); empty (no stock / no cards / no sales yet); success (data displayed, edits saved); error (fetch or save failure → message and retry); recovery (retry).

Inventory

• Information/state: the shop's stock items with name, price, quantity, shelf category and AR product mapping; GRV (goods received voucher) records; price edit state. Restricted to Shop Owner.
• Primary actions: add a stock item; edit a stock item; edit a price; generate a GRV for received stock.
• Supporting actions: search and filter stock items; assign a shelf category; review GRV history.
• Domain entities: stock item (name, price, quantity, shelf category, AR product mapping), GRV record (reference, date, received lines and quantities), price change record.
• Component responsibilities: stock item table with search, add/edit stock item form, price edit control, shelf category selector, GRV generator and GRV history list.
• States: loading (stock and GRV data fetching); empty (no stock items yet → add prompt; no GRVs yet); success (item added/edited, price saved, GRV generated with confirmation); error (validation or save failure → inline error with values retained); recovery (retry save).

Shop Operations

• Information/state: the shop's promotions with their terms and conditions, promotion prices and promotion dates; cash-out state; end-of-day state. Restricted to Shop Owner. Promotion capability depends on the subscription tier the shop selected.
• Primary actions: create and run a promotion (terms and conditions apply); cash out; run end of day.
• Supporting actions: review active and past promotions; review the end-of-day summary before closing; view cash-out history.
• Domain entities: promotion (name, promotion price, start date, end date, terms and conditions, affected items), cash-out record, end-of-day record (sales totals, payment mix, closing summary).
• Component responsibilities: promotion builder with terms-and-conditions acknowledgement and date range, promotion list, cash-out panel, end-of-day runner with summary, tier-capability notice when the selected tier does not include promotions.
• States: loading (promotions and day data fetching); empty (no promotions yet; no sales for the day); success (promotion published, cash-out recorded, end of day completed with summary); error (terms not acknowledged, invalid date range, tier does not include promotions, save failure → inline error with values retained); recovery (correct and retry).

Cashier Web

• Information/state: hybrid sales counter — Cart, Split payment, M-Pesa STK Push, Cash/Digital toggle. Restricted to Cashier.
• Primary actions: build cart; toggle cash/digital; enter cash amount and split payment; send M-Pesa STK Push; complete sale.
• Supporting actions: remove cart line; adjust quantity; retry STK Push.
• Domain entities: cart, cart line, payment (cash portion, digital portion, method), M-Pesa STK Push request, sale record.
• Component responsibilities: cart panel with printed price tags, cash/digital toggle, split payment form, STK Push trigger and status, receipt/confirmation.
• States: loading (STK Push pending, awaiting callback); empty (empty cart); success (full cash → SUCCESS/FULL_CASH; split → digital remainder initiated; callback confirms); error (STK Push failure/timeout → retry or switch method); recovery (retry, fall back to cash).

Shop Browse

• Information/state: the list of shops available to buy from; the selected shop's shelf categories with the items on those shelves. Restricted to Mobile Shopper.
• Primary actions: select which shop to buy from; open a shelf category; open an item.
• Supporting actions: switch shop; search items within the selected shop; open Shop Map for a selected item.
• Domain entities: shop (name, location, logo), shelf category, stock item with price and promotion data.
• Component responsibilities: shop selector, shelf category list, item grid per shelf, item detail entry point, map entry control.
• States: loading (shop and shelf data fetching); empty (no shops available; selected shop has no items on a shelf); success (shop selected, shelves and items displayed); error (fetch failure → message and retry); recovery (retry or switch shop).

Shop Map

• Information/state: in-shop map of the selected shop with directions from the shopper's position to the shelf holding the required product. Restricted to Mobile Shopper.
• Primary actions: follow map directions to the required product.
• Supporting actions: change destination product; return to Shop Browse.
• Domain entities: shop floor map, shelf location, destination product.
• Component responsibilities: map canvas with shelf markers, route/direction overlay, destination label, back-to-browse control.
• States: loading (map and shelf locations loading); empty (no map published for the shop → fall back to shelf category browsing); success (route displayed to the destination shelf); error (map or location unavailable → message with fallback to shelf browsing); recovery (retry or browse shelves instead).

User Mobile

• Information/state: AR Scanning (product recognition) showing expiry date, promotion price and promotion dates, and price; Cart; in-app payment; remote purchase with collection time selection; Trial status. Restricted to Mobile Shopper.
• Primary actions: scan a product with AR; read expiry date, promotion price and dates and price from the scan result; add the scanned product to cart; pay for items in the app without going to the cashier; select what to buy remotely and when to collect; view trial status; proceed to Item Checkout.
• Supporting actions: remove cart line; adjust quantity; retry scan; refresh trial status; change the selected collection time.
• Domain entities: recognized product (expiry date, promotion price, promotion dates, price), cart, cart line, order, collection selection (collection time), payment, trial (start date, 3-day window, expiry), P85.00 fee.
• Component responsibilities: camera/AR scanner, scan result panel with expiry date, promotion price and dates and price, cart panel, in-app payment control, remote purchase and collection-time selector, trial status stamp and checkout gate.
• States: loading (camera init, recognition in progress, payment in progress); empty (no scans / empty cart); success (product recognized with expiry, promotion and price data and added to cart; in-app payment confirmed; remote order placed with collection time; trial active); error (camera permission denied, recognition failure, payment failure, checkout blocked at trial expiry → prompt to pay P85.00); recovery (retry scan, retry payment, pay fee, resume).

Order History

• Information/state: the Mobile Shopper's purchase history and reports, including which shop each item was bought from, order date, items, amounts and collection details. Restricted to Mobile Shopper.
• Primary actions: view purchase history; open an order's detail; read purchase reports by shop.
• Supporting actions: filter by shop or period; open the shop of a past purchase.
• Domain entities: order (date, shop, items, amounts, payment method, collection details), purchase report grouped by shop.
• Component responsibilities: order list, order detail view, shop attribution label per order, report summary grouped by shop, period filter.
• States: loading (history fetching); empty (no purchases yet); success (orders and reports displayed with shop attribution); error (fetch failure → message and retry); recovery (retry).

3. Functional Requirements

FR-1 — Product identity. As a visitor, I should see that the product is the Omni-POS Hybrid Ecosystem, powered by Neo Systems Africa, so that I understand who makes it. (explicit) Observable acceptance: the tagline "Powered by; Neo Systems Africa!" and product name appear on the public entry.

FR-2 — Splash Screen timing and animation. As any user, I should see a Splash Screen for 2.5s with a logo fade-in and a "Neo Systems Africa" pulse, so that the brand registers while the session is checked. (explicit) Observable acceptance: the splash displays for 2.5s with the specified animation.

FR-3 — Splash session routing. As any user, I should be routed by the Splash Screen according to session state — existing session → Dashboard, no session → Onboarding. (explicit) Failure/recovery: if the session probe fails, treat as no session and route to Onboarding. Continuation: the user can authenticate from Onboarding → AUTH.

FR-4 — Onboarding content. As a new user, I should see an Onboarding slider or video with three messages: "Welcome to Omni-POS", "Hybrid Sales + AR Scanning", and "AI Assistants: Eliana, Caitlin, Alisha, Florence, Edmund, Neo". (explicit) Observable acceptance: all three messages are reachable in the slider/video.

FR-5 — Onboarding precedes AUTH. As a new user, I should complete Onboarding before AUTH. (required_inference) Observable acceptance: continuing from Onboarding leads to AUTH.

FR-6 — Authentication methods. As a user, I should authenticate by Biometric, Phone (OTP) or Payoneer OAuth, with FIDO2 (WebAuthn) on all authentication pages. (explicit) Observable acceptance: each method can establish a session; FIDO2 ceremony is used on every authentication page. Failure/recovery: invalid OTP → inline error and resend; failed ceremony → retry; denied OAuth → return to AUTH with message.

FR-7 — Identity verification. As a user, I should verify identity through the chosen method and receive a session. (required_inference) Observable acceptance: successful verification establishes a session and routes to the role surface.

FR-8 — Admin Web superuser control. As an Admin (Superuser), I should have superuser control over User management, System logs, Trial overrides and AI assistant tuning. (explicit) Observable acceptance: each of the four areas is operable and changes persist. Failure/recovery: rejected save → inline error with values retained and retry.

FR-9 — Shop Owner Web. As a Shop Owner, I should manage Inventory management, Membership cards, Sales reports and Trial analytics. (explicit) Observable acceptance: inventory edits persist; membership cards can be issued and looked up; sales reports and trial analytics display. Failure/recovery: fetch/save failure → message and retry.

FR-9a — Subscription tier catalogue. As an Admin (Superuser), I should set the three subscription tiers and the options included in each tier, so that shop registration offers the correct plans. (explicit) Observable acceptance: the tiers Starter (P975/month), Pro (P1850/month) and Premium (P2850/month) exist with different options per tier, and edits to a tier's price or options persist and are reflected at Shop Registration.

FR-9b — Shop registration with tier selection. As a Shop Owner, I should select a subscription option to register my shop on the SaaS Omni Hybrid-POS system, supplying shop name, location, logo, contact email and mobile numbers, from the three tiers of the system. (explicit) Observable acceptance: registration requires a selected tier plus shop name, location, logo, contact email and mobile numbers; on submit the shop is registered on the selected tier and the Shop Owner reaches Shop Owner Web. Failure/recovery: missing or invalid field → inline error with values retained and resubmit.

FR-9c — Tier-dependent POS options. As a Shop Owner, I should get the options that belong to the tier I selected, so that promotions and other capabilities match my subscription. (explicit) Observable acceptance: the options available in the POS follow the selected tier's option set as defined by the Super Admin; a capability not included in the tier is not offered and shows a tier-capability notice.

FR-9d — Shop Owner POS operations. As a Shop Owner, I should run my own promotions (terms and conditions apply), cash out, run end of day, generate GRVs, add stock items, edit stock items and edit prices within my POS system on the platform. (explicit) Observable acceptance: a promotion can be created with promotion price, dates and acknowledged terms and conditions; cash out and end of day complete with a recorded summary; a GRV is generated for received stock; stock items can be added and edited; prices can be edited and persist. Failure/recovery: terms not acknowledged, invalid date range, tier without promotions, or save failure → inline error with values retained and retry.

FR-10 — Cashier Web hybrid sales. As a Cashier, I should run hybrid sales with a Cart, Split payment, M-Pesa STK Push and a Cash/Digital toggle. (explicit) Observable acceptance: cart builds; toggle switches method; split payment and STK Push execute.

FR-11 — User Mobile features. As a Mobile Shopper, I should use AR Scanning (product recognition), Cart, Order history and Trial status. (explicit) Observable acceptance: a product is recognized and can be added to cart; orders appear in history; trial status is visible. Failure/recovery: camera permission denied or recognition failure → retry prompt.

FR-11a — Shop selection and shelf browsing. As a Mobile Shopper, I should select which shop to buy from and see shelf categories with the items on the same shelves, including when buying from home to later pick the items. (explicit) Observable acceptance: a shop can be selected; its shelf categories list the items held on those shelves; items can be opened from a shelf.

FR-11b — In-shop map directions. As a Mobile Shopper, I should navigate the shop with map directions to reach the product I require faster than looking for a merchandiser. (explicit) Observable acceptance: from a selected product, a map shows directions to the shelf holding it. Failure/recovery: map unavailable → fall back to shelf category browsing.

FR-11c — Scan reveals expiry, promotion and price. As a Mobile Shopper, I should see through scanning the expiry dates, promotion prices and dates, and prices of a product, and be able to add the scanned item to my cart. (explicit) Observable acceptance: a scan result shows expiry date, promotion price, promotion dates and price, and the scanned item can be added to cart.

FR-11d — In-app payment without the cashier. As a Mobile Shopper, I should pay for items through the mobile app without having to go to the cashier. (explicit) Observable acceptance: payment completes in the app and the order is recorded without a cashier step. Failure/recovery: payment failure → retry.

FR-11e — Remote purchase and collection time. As a Mobile Shopper, I should remotely select what to buy and when to collect when I am not in the shop physically. (explicit) Observable acceptance: an order can be placed remotely with a selected collection time and is recorded with that collection selection.

FR-11f — Purchase history and reports by shop. As a Mobile Shopper, I should know where I bought what from my reports and history of purchases in my account. (explicit) Observable acceptance: Order History lists past orders with the shop each item was bought from and provides reports grouped by shop.

FR-12 — Trial start. As a new user, I should start a 3-day full browsing trial and be able to browse, add to cart and use AR during it. (explicit) Observable acceptance: trial begins at sign-up; browsing, cart and AR are available for 3 days.

FR-13 — Payment only at Item Checkout or Trial Expiry. As a user, I should be asked to pay only at Item Checkout or at Trial Expiry. (explicit, hard constraint) Observable acceptance: no payment prompt appears during browsing, cart building or AR use; payment is triggered at checkout or after day 3.

FR-14 — P85.00 once-off fee. As a user, I should pay a P85.00 once-off account opening fee when payment is triggered. (explicit, hard constraint) Observable acceptance: the fee amount is P85.00 and is charged once.

FR-15 — Trial counter and checkout blocker. As the system, the trial-service should count 3 days and block checkout until the P85.00 fee is paid. (required_inference) Observable acceptance: checkout is blocked at expiry until fee capture succeeds; after capture, checkout proceeds.

FR-16 — Split payment logic. As a Cashier, I should have the cash amount applied first and the remaining amount sent to the digital method. (explicit) Observable acceptance: processSplitPayment(cartTotal, cashAmount, digitalMethod) computes remaining = cartTotal - cashAmount; if remaining > 0, initiate the digital transaction for remaining; otherwise return {status: 'SUCCESS', method: 'FULL_CASH'}.

FR-17 — M-Pesa STK Push. As a Cashier, I should send an M-Pesa STK Push with BusinessShortCode NEOPOS, the amount, the user's phone number, and CallBackURL https://api.appforcestudio.com/neo/callback. (explicit) Observable acceptance: POST /mpesa/stkpush/v1/process carries those fields; the callback confirms the payment state. Failure/recovery: timeout or failure → retry or switch method.

FR-18 — AI assistants. As a user, I should see the six AI assistants — Eliana (Strategy), Caitlin (Tech), Alisha (Payments), Florence (Support), Edmund (Admin), Neo (Operations). (explicit) Observable acceptance: all six names and roles appear in onboarding and are tunable from Admin Web.

FR-19 — Security manifest. As the system, storage encryption should use AES-256-GCM and transactions should follow PCI-DSS 4.0. (explicit, hard constraint) Observable acceptance: data at rest is AES-256-GCM encrypted; payment flows conform to PCI-DSS 4.0.

FR-20 — Payment gateways. As the system, payments should route through Payoneer and M-Pesa. (explicit) Observable acceptance: both gateways are integrated; Payoneer OAuth and API are used; M-Pesa STK Push is used.

FR-21 — Admin role controls Admin Web. As an Admin (Superuser), I should be the role that controls Admin Web access. (required_inference) Observable acceptance: only the Admin role reaches Admin Web.

FR-22 — CHANGELOG.md discipline. As the builder, I should read CHANGELOG.md first, create it if missing, generate only features not yet marked Stable, never regenerate completed features, append Date | Feature | Status after each build step, and track Technical Debt separately. (explicit, hard constraint) Observable acceptance: CHANGELOG.md exists at root with the specified format and entries.

4. User Personas

Admin (Superuser)

• Product context: holds superuser control of the Omni-POS ecosystem.
• Primary goal: keep the system healthy and correctly configured.
• Distinct responsibilities: User management, reading System logs, setting Trial overrides, and AI assistant tuning for Eliana, Caitlin, Alisha, Florence, Edmund and Neo.
• Inputs/decisions: which users to manage, which log entries to inspect, which trial overrides to apply, how each assistant should be tuned.
• Interactions: with the system (logs, users) and with the assistant roster; overrides affect the trial lifecycle experienced by other roles.
• Observable success: changes persist and are confirmed; logs are readable; overrides take effect.

Shop Owner

• Product context: runs the shop on the SaaS platform and watches stock and sales.
• Primary goal: keep inventory accurate, run the shop's own promotions and day operations, and understand sales and trial performance.
• Distinct responsibilities: selecting a subscription tier and registering the shop (shop name, location, logo, contact email and mobile numbers); Inventory management; Membership cards; Sales reports; Trial analytics; running promotions (terms and conditions apply), cash out, end of day, GRVs, adding and editing stock items and editing prices.
• Inputs/decisions: which tier to subscribe to, shop details, stock edits, price edits, promotion terms and dates, membership card issuance, report period selection, when to cash out and close the day.
• Interactions: with the Super Admin's tier catalogue; with inventory data consumed by Cashier Web, Shop Browse and User Mobile AR mapping; with sales records produced by cashier and in-app sales.
• Observable success: shop registered on the selected tier; inventory reflects reality; promotions run within their terms and dates; cash out and end of day complete with a summary; GRVs generated; membership cards are usable; reports and trial analytics display.

Cashier

• Product context: sells at the counter in hybrid mode.
• Primary goal: complete a sale quickly with the right payment mix.
• Distinct responsibilities: building a Cart, Split payment, M-Pesa STK Push, Cash/Digital toggle.
• Inputs/decisions: cart contents, cash amount, digital method, whether to retry STK Push.
• Interactions: with the Mobile Shopper's payment confirmation via M-Pesa; with inventory stock.
• Observable success: full-cash sale returns SUCCESS/FULL_CASH; split sale initiates the digital remainder; callback confirms.

Mobile Shopper

• Product context: browses and buys from the mobile app, in the shop or remotely.
• Primary goal: find products quickly by shelf browsing, map directions and AR scanning, and check out within the trial.
• Distinct responsibilities: selecting which shop to buy from; browsing shelf categories with the items on those shelves; in-shop map directions to a product; AR Scanning (product recognition) showing expiry dates, promotion prices and dates and prices; Cart; paying in the app without going to the cashier; remote purchase with a chosen collection time; Order history and purchase reports showing where items were bought; Trial status.
• Inputs/decisions: which shop to buy from, which shelf or product to open, what to scan, what to add to cart, when to pay in the app, what to buy remotely and when to collect, when to check out, whether to pay the P85.00 fee at expiry.
• Interactions: with the selected shop's shelf and stock data; with the in-app payment flow; with the trial-service.
• Observable success: shop selected; shelves and items browsed; directions shown to the product; product recognized with expiry, promotion and price data and added; in-app payment confirmed; remote order placed with collection time; purchase history and reports show where items were bought; trial status visible; checkout unblocked after fee payment.

5. Core User Flows

Flow A — Anonymous visitor to authenticated session

1. Visitor opens Landing; reads product intent, trial terms (3-Day Full Browsing Trial, P85.00 once-off) and assistant roster.
2. Visitor enters the product; Splash Screen shows for 2.5s with logo fade-in and "Neo Systems Africa" pulse while the session is checked.
3. No session → routed to Onboarding; visitor advances the slider/video through "Welcome to Omni-POS", "Hybrid Sales + AR Scanning", and the six assistants.
4. Visitor continues to AUTH; chooses Biometric, Phone (OTP) or Payoneer OAuth under FIDO2.
5. On success, a session is established and the user is routed to the role surface (Admin Web, Shop Owner Web, Cashier Web or User Mobile).
6. Failure: invalid OTP → inline error and resend; failed ceremony → retry; denied OAuth → return to AUTH. Continuation: retry any method.

Flow B — Returning user with session

1. User opens the product; Splash Screen runs 2.5s and detects an existing session.
2. Routed directly to the Dashboard (role surface). No Onboarding or AUTH required.

Flow C — Mobile Shopper trial and AR purchase

1. Mobile Shopper signs up and the 3-day trial starts; User Mobile shows Trial status.
2. Shopper uses AR Scanning to recognize a product; adds it to Cart.
3. Shopper browses and adds items freely during the trial — no payment prompt.
4. At Item Checkout, payment is triggered: the P85.00 once-off account opening fee is required; trial-service blocks checkout until fee capture succeeds.
5. On successful capture, checkout proceeds and the order appears in Order history.
6. Failure: camera permission denied or recognition failure → retry prompt. Trial Expiry (after day 3) also triggers payment; after payment, browsing and checkout resume.

Flow D — Cashier hybrid sale

1. Cashier opens Cashier Web; builds a Cart (each item shown as a printed price tag).
2. Cashier uses the Cash/Digital toggle to choose the method.
3. Full cash: processSplitPayment returns {status: 'SUCCESS', method: 'FULL_CASH'}.
4. Split: Cashier enters cash amount; remaining = cartTotal - cashAmount; if remaining > 0, payment-service initiates the digital transaction for the remainder.
5. For M-Pesa, payment-service sends POST /mpesa/stkpush/v1/process with BusinessShortCode NEOPOS, Amount, PhoneNumber and CallBackURL https://api.appforcestudio.com/neo/callback; the callback confirms.
6. Failure: STK Push timeout/failure → retry or switch method. Continuation: sale completes on confirmation.

Flow E — Shop Owner registration and back office

1. Shop Owner opens Shop Registration and compares the three tiers set by the Super Admin — Starter (P975/month), Pro (P1850/month), Premium (P2850/month) — with their different options.
2. Shop Owner selects a subscription option and supplies shop name, location, logo, contact email and mobile numbers; the shop is registered on the selected tier.
3. Shop Owner opens Shop Owner Web; the shop's tier and included options are shown.
4. In Inventory, adds stock items, edits stock items, edits prices and generates GRVs; stock and AR product mappings are consumed by User Mobile and Shop Browse.
5. In Shop Operations, runs the shop's own promotions (terms and conditions apply, subject to the selected tier), cashes out and runs end of day.
6. Issues and looks up Membership cards; reads Sales reports and Trial analytics.
7. Failure: missing/invalid registration field, terms not acknowledged, tier without promotions, or fetch/save failure → inline message with values retained and retry.

Flow G — Mobile Shopper shop selection, map and in-app purchase

1. Mobile Shopper opens Shop Browse and selects which shop to buy from.
2. Browses shelf categories with the items on the same shelves — including from home, to later pick the items.
3. Opens Shop Map to follow map directions to the required product instead of looking for a merchandiser.
4. Scans the item in User Mobile; the scan shows expiry date, promotion price and promotion dates, and price; adds the scanned item to Cart.
5. Pays for the items through the mobile app without going to the cashier; or, when not in the shop physically, selects what to buy remotely and when to collect.
6. The order is recorded and appears in Order History, where purchase history and reports show which shop each item was bought from.
7. Failure: camera permission denied or recognition failure → retry prompt; payment failure → retry; map unavailable → fall back to shelf browsing.

Flow F — Admin superuser operations

1. Admin opens Admin Web (role-restricted).
2. Manages users; reads System logs; sets Trial overrides; tunes AI assistants (Eliana, Caitlin, Alisha, Florence, Edmund, Neo).
3. Changes persist with confirmation; rejected saves show inline errors with values retained.

6. Visuals Colors and Theme

Muse: Virgil Abloh. Headline direction: "Remixed checkout" — label-and-tag language applied to a hybrid sales system.

Palette (light mode):

• Background: #F2F0EB (warm concrete grey, ~70% of surface)
• Surface: #FFFFFF
• Text: #111111
• Primary: #111111
• Accent: #FF4D00 (safety orange, ~10%, reserved for payment and trial signals)
• Muted: #8A8781
• Status: green #16A34A (active/safe), yellow #FACC15 (warning), red #EF4444 (critical)

Typography: Headings Archivo — uppercase, wide tracking, weight 800. Body Space Grotesk. Modular scale 1.333: headings 40/64/96/128px; body 16/18px. Quotation marks around key labels. Inter, Roboto and Poppins are forbidden.

Shape language: Hard corners, 2px black rules, rectangular label tags, hazard-stripe bands. No soft shadows, no rounded cards with hover lift, no gradient blobs or glass panels.

Layout: Exposed 12-column grid with visible hairlines; sections read as stacked shipping labels and price tags.

Motion: Snappy 120ms state flips; slow ticker tape in the header; no bounce or fade.

Imagery: Product photos on concrete with orange gaffer-tape marks; bold black pictograms for cash, card and M-Pesa.

Readability rule: headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (e.g. clamp(...)) to fit; no element covers readable text or controls. Decoration and motion may crop, bleed, rotate or overlap freely. Tickers and scrollable rows may cross edges by design and must remain fully readable as items pass; under prefers-reduced-motion, provide a static arrangement (wrap or horizontal scroll) so every item can be brought fully into view.

7. Signature Design Concept

The public entry is a full-width black band holding the wordmark OMNI-POS in 128px Archivo (clamped down for smaller viewports), with a small orange P85.00 price tag clipped to its corner. Beneath it runs a black ticker tape of live sales states in uppercase. The right third shows one cashier screen photographed on concrete. Every section title sits inside a white label tag with a 2px black outline. The trial counter reads 3-DAY in a safety-orange stamp. Payment buttons use a diagonal hazard stripe on hover. The cashier cart shows each item as a printed price tag with a barcode strip. This concept recomposes only accepted content and controls — the trial offer, the roles, the assistants, the entry controls — and introduces no new behaviour.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the OMNI-POS wordmark in a black band with the orange P85.00 price tag, and the ticker tape of sales states beneath.
• Input → transformation → outcome thesis: as the visitor arrives, the ticker tape scrolls continuously through uppercase sales states; hovering a payment control flips it to a diagonal hazard stripe in 120ms; the trial stamp reads 3-DAY. The outcome is a visitor who understands the trial and the P85.00 fee and can enter the product.
• Motion vocabulary: snappy 120ms state flips, slow continuous ticker, no bounce, no fade.
• Composed first frame: black band, 128px wordmark, clipped orange price tag, ticker tape running beneath, cashier screen on concrete at right.
• Reduced-motion state: ticker becomes a static wrapped row of sales states (or horizontally scrollable) so every item is fully readable; state flips become instant.

9. Non-Functional Requirements

• NFR-1 (explicit): Storage encryption uses AES-256-GCM; key supplied via AES_256_GCM_KEY.
• NFR-2 (explicit): Transactions follow PCI-DSS 4.0.
• NFR-3 (explicit): Authentication uses FIDO2 (WebAuthn) on all authentication pages.
• NFR-4 (explicit): Payment gateways are Payoneer and M-Pesa; callback URL base https://api.appforcestudio.com/neo; M-Pesa callback https://api.appforcestudio.com/neo/callback.
• NFR-5 (explicit): Required environment variables: MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET, PAYONEER_CLIENT_ID, AES_256_GCM_KEY.
• NFR-6 (explicit): Deployment via Docker; Kubernetes optional.
• NFR-7 (explicit): Splash Screen duration is 2.5s.
• NFR-8 (explicit): Trial is 3 days; fee is P85.00 once-off; payment only at Item Checkout or Trial Expiry.
• NFR-9 (explicit): Build discipline — read CHANGELOG.md first, create if missing, never regenerate completed features, append Date | Feature | Status, track Technical Debt separately.
• NFR-10 (required_inference): Readable text and controls remain whole at 375px, 768px and 1280px per the creative direction's readability rule.

10. Tech Stack

• Web frontend: React + Vite (micro-frontend modules); admin dashboard React + Tailwind.
• Mobile frontend: React Native (Expo) for AR + camera.
• Backend microservices (Go): auth-service (FIDO2, Phone OTP, Payoneer OAuth, session management), trial-service (3-day counter, checkout blocker, P85 fee capture), payment-service (split payment, M-Pesa STK Push, Payoneer API), inventory-service (stock, AR product mapping, shelf categories, GRVs, price edits, promotions, cash out and end-of-day records).
• Shared backend: FastAPI process for application APIs and domain modules.
• Application database: MariaDB for application-owned persistent data.
• AI gateway: LiteLLM gateway for the backend's model-provider calls, backed by its own PostgreSQL instance (separate from application-owned storage).
• Deployment: Docker; Kubernetes optional.
• Target platform: https://www.lovable.dev.

11. Assumptions and Constraints

• A-1: The four personas (Admin (Superuser), Shop Owner, Cashier, Mobile Shopper) are the closed active-human set.
• A-2: Role-restricted access to Admin Web, Shop Registration, Shop Owner Web, Inventory, Shop Operations, Cashier Web, Shop Browse, Shop Map, User Mobile and Order History follows the supplied page contract; Landing, Splash Screen, Onboarding and AUTH are anonymously reachable.
• A-8: The three subscription tiers and the options inside each tier are Super Admin–defined data, not hard-coded; the prices Starter P975/month, Pro P1850/month and Premium P2850/month are the current values of that catalogue.
• A-9: Promotion capability is tier-dependent; the exact option set per tier is set by the Super Admin and is not otherwise specified in the requirement thread.
• A-10: Shop floor maps and shelf locations are shop-owned data maintained per shop; where a shop has no published map, shelf category browsing remains available.
• A-3: The "Dashboard" referenced by the Splash Screen routing is the authenticated role surface for the signed-in user.
• A-4: The CHANGELOG.md engine is a build-process obligation, not an end-user feature.
• A-5: Kubernetes is optional per the source.
• A-6: LiteLLM's PostgreSQL store is gateway infrastructure, not application-owned customer data.
• A-7: The creative direction is authoritative for visual and motion decisions; the readability rule takes precedence over any cropping of readable text or controls.

12. Glossary

• Omni-POS Hybrid Ecosystem: the product; hybrid retail POS powered by Neo Systems Africa.
• Hybrid sales: combined cash and digital selling at the counter.
• Split payment: cash applied first, remainder sent to the digital method.
• M-Pesa STK Push: provider-initiated payment prompt using BusinessShortCode NEOPOS.
• Payoneer OAuth: provider-owned authorization used as an authentication method and payment gateway.
• FIDO2 (WebAuthn): authentication standard applied on all authentication pages.
• 3-Day Full Browsing Trial: trial allowing browse, cart and AR for 3 days.
• P85.00 once-off account opening fee: fee required only at Item Checkout or Trial Expiry.
• AI assistants: Eliana (Strategy), Caitlin (Tech), Alisha (Payments), Florence (Support), Edmund (Admin), Neo (Operations).
• Subscription tier: one of three Super Admin–defined plans — Starter (P975/month), Pro (P1850/month), Premium (P2850/month) — each with different included options.
• Shop registration: the Shop Owner's act of selecting a tier and supplying shop name, location, logo, contact email and mobile numbers.
• GRV: goods received voucher generated by the Shop Owner for received stock.
• Cash out: Shop Owner operation recording a cash withdrawal from the shop's takings.
• End of day: Shop Owner operation closing the trading day with a recorded summary.

• Shelf category: a grouping of items held on the same shelf in a shop, browsable by the Mobile Shopper.
• Shop Map: in-shop map directions guiding the Mobile Shopper to the shelf holding a required product.
• Remote purchase and collection: selecting items and a collection time in the app when not physically in the shop.
• CHANGELOG.md engine: build discipline tracking Date | Feature | Status and Technical Debt.
• LiteLLM: gateway for the backend's model-provider calls.