lunarfront-app/planning/28_Frontend_Strategy.md

LunarFront Platform

Frontend Strategy — Multiple UI Surfaces

Version 1.0 | Draft

1. Overview

LunarFront serves different users in different contexts — a store owner at their desk, a cashier at the counter, a staff member receiving stock in the back room, and a salesperson at a trade show. One UI cannot serve all of these well.

The platform uses a single backend API with multiple purpose-built frontends. Each frontend is a separate package in the monorepo, shares the same @lunarfront/shared schemas and types, and calls the same REST API. The backend doesn't know or care which frontend is making the request.

2. Frontend Packages

2.1 Admin UI — packages/admin

Status: Active development (current)

Attribute	Detail
Form factor	Desktop / laptop, large tablet
Stack	React, Vite, TanStack Router, TanStack Query, shadcn/ui
Users	Store owner, manager, back-office staff
Access	Web browser

Purpose: Full management interface. Everything that isn't a real-time transaction happens here — accounts, members, inventory configuration, RBAC, roles, reports, settings, lesson scheduling, repair management, vault.

Design priorities:

• Dense information display (data tables, detail pages)
• Keyboard-friendly (tab navigation, search)
• Multi-column layouts, sidebars, dialogs
• Not optimized for touch or small screens — that's intentional

2.2 POS UI — packages/pos

Status: Planned

Attribute	Detail
Form factor	Counter-mounted tablet (10"+) or touchscreen monitor
Stack	React, Vite (same toolchain as admin)
Users	Cashier, sales associate
Access	Web browser (full-screen / kiosk mode)

Purpose: Point-of-sale for in-store transactions. Staff stares at this 8 hours a day. Every interaction must be fast and require minimal taps.

Design priorities:

• Always-on, single-screen (no page navigation)
• Large touch targets (44px+ minimum)
• Fast product search (keyboard wedge barcode scanner + text search)
• Cart management (add, remove, adjust quantity, apply discount)
• Payment flow (cash, card via terminal, split payment)
• Cash drawer integration
• Receipt printing (thermal printer via browser print or ESC/POS)
• Session management (clock in/out, cash drawer open/close, X/Z reports)
• Offline resilience — queue transactions if network drops, sync when back

PIN unlock:

The POS terminal stays authenticated but locks between use. Staff unlock with a 4-6 digit PIN instead of email/password. The PIN maps to their real user account — every action (sale, void, drawer open) is attributed to the person who unlocked.

• Each user sets a numeric PIN from their profile or admin assigns one
• PIN is stored as a bcrypt hash on the user record (separate from password)
• POS lock screen shows a numeric keypad — tap PIN, unlock, start selling
• Auto-locks after configurable idle timeout (default: 2 minutes)
• Manual lock button always visible
• Shift change: current user walks away, screen locks, next user enters their PIN
• Wrong PIN: brief delay, max 5 attempts then require full login
• PIN unlock issues a short-lived JWT (or extends the existing session) scoped to POS permissions
• Backend: POST /v1/auth/pin-login — accepts { pin }, returns token with same user identity and permissions
• PIN is optional — users without a PIN set must use full email/password login on the POS

This gives full audit trail (who did what) without the friction of typing credentials hundreds of times a day.

Discounts & price overrides:

• Line item discount (percentage or flat dollar amount)
• Whole-cart discount (e.g. 10% off everything)
• Price override with reason code (item rings up wrong, manual correction)
• Manager override: cashier attempts a discount or void above their permission level, manager punches their PIN to approve without taking over the session. Logged as "approved by [manager] for [cashier]"
• Configurable discount limits per role (e.g. sales associate can give up to 10%, manager up to 25%, admin unlimited)

Parked carts / layaway:

• Park a cart — customer wants to keep shopping or come back later
• Multiple parked carts, each tagged with customer name or account
• Retrieve a parked cart to resume the sale
• Layaway: park with a deposit, schedule remaining payments
• Auto-expire parked carts after configurable period (default: 7 days)

Gift cards & store credit:

• Sell a gift card (physical or digital, generates a unique code)
• Redeem gift card as payment method (scan or type code)
• Check balance
• Issue store credit (returns, adjustments) — tied to an account
• Store credit appears as a payment option when account is linked to the sale

Returns:

• With receipt: lookup transaction by receipt number or barcode, select items, refund to original payment method
• Without receipt: store credit only, capped amount (configurable), requires manager override
• Exchange: return + new sale in one transaction
• Restocking fee support (percentage or flat, configurable per category)
• Returned items: prompt for condition (resellable, damaged, defective) — updates inventory accordingly

End of day / cash management:

• Open session: cashier counts starting cash, enters amount, system records
• Cash drops: mid-shift safe drops, logged with amount and time
• Close session: two modes:
  • Counted close: cashier counts the drawer, enters totals by denomination, system calculates over/short
  • Blind close: cashier counts and enters total without seeing expected amount — prevents fudging
• Z report: end-of-day summary — gross sales, net sales, tax collected, payment method breakdown (cash, card, gift card, store credit), refunds, discounts given, over/short
• X report: mid-day snapshot (same data as Z but doesn't close the session)
• All reports printable on receipt printer

Training mode:

• Toggle per POS session — transactions don't hit real inventory or accounting
• Visually distinct: large "TRAINING MODE" banner across the screen, different background color
• Manager enables/disables via their PIN
• Training transactions are logged separately for review but don't affect reports or stock

Customer-facing display:

• Second screen (or portion of a split screen) showing the customer what's being rung up
• Line items, quantities, prices, running total
• Shows payment status ("Insert card", "Approved", "Change due: $4.25")
• Some jurisdictions legally require itemized display during transaction
• Configurable: on/off, which screen, store branding/logo

Quick keys / favorites:

• Configurable grid of frequently sold items (strings, picks, reeds, cables, lesson payments)
• Admin configures the grid layout (drag and drop in admin UI)
• Supports categories/tabs (e.g. "Accessories", "Lessons", "Repairs")
• Faster than searching — one tap to add to cart
• Can also map to common actions (open drawer, apply house discount, gift card sale)

Receipts:

• Thermal printer via ESC/POS (USB or network)
• Browser print fallback with receipt-formatted CSS
• Email receipt option (if customer has account with email)
• Text/SMS receipt (future, via email system)
• Configurable header/footer (store name, address, return policy, social media)
• Barcode/QR on receipt for easy return lookup

Key screens:

1. Lock screen — numeric keypad, current time, store name
2. Sale screen — product search (left), quick keys (top), cart (right), totals + pay button (bottom)
3. Payment screen — amount due, payment method selection, card terminal status, change calculation, tip (optional)
4. Return/exchange screen — lookup original transaction, select items, refund method, condition prompt
5. Parked carts — list of held transactions, tap to resume
6. Drawer management — open session, cash drops, close session with denomination counting
7. Reports — X report, Z report, transaction history for current session

Hardware integration:

• Barcode scanner: keyboard wedge (types into focused input, no special API)
• Card reader: local network or USB terminal via Stripe Terminal SDK or Global Payments SDK
• Cash drawer: triggered via receipt printer (kick pulse) or USB relay
• Receipt printer: ESC/POS over USB or network, or browser window.print() with receipt-formatted CSS
• Customer display: secondary screen via window.open() or dedicated display API
• Scale (future): for items sold by weight

2.3 Floor App — packages/floor

Status: Planned

Attribute	Detail
Form factor	Phone or small tablet
Stack	React Native (Expo) or PWA
Users	Sales staff on floor, inventory staff, trade show sales
Access	Native app (iOS/Android) or PWA in Safari/Chrome

Purpose: Two modes in one mobile app — inventory management and mobile sales. Both are walk-around-the-store (or walk-around-a-trade-show) workflows with scanning, big inputs, and minimal typing.

Design priorities:

• Phone-first layout (single column, stacked)
• Camera barcode scanning (no external scanner needed)
• Large buttons, minimal text input
• Works on cellular (trade shows) and store WiFi
• Offline support for inventory counts (sync when connected)

Inventory Mode

Purpose: Receiving, cycle counts, transfers, shelf checks.

Key screens:

1. Receive stock — scan items, enter quantities, confirm receipt against purchase order
2. Cycle count — scan location/shelf, scan items, enter counts, submit discrepancies
3. Quick lookup — scan barcode, see product details, stock levels across locations, price history
4. Transfer — scan items to move between locations
5. Condition check — scan item, update condition (new, used, damaged), add notes/photo

Mobile POS Mode

Purpose: Sales at trade shows, on the shop floor, off-site events.

Key screens:

1. Quick sale — search/scan products, add to cart, take payment
2. Payment — Bluetooth card reader integration, or manual card entry
3. Customer lookup — search by name/phone/account number for account-linked sales
4. Receipt — email or text receipt (no printer at a trade show)

Build Strategy

Phase 1 — PWA:

• Build as a web app with mobile-optimized UI
• "Add to Home Screen" for app-like experience
• Camera scanning via navigator.mediaDevices + barcode detection library
• Local network card reader for payments
• No App Store, no developer cert, works on any device

Phase 2 — Native (if needed):

• React Native with Expo
• Reuses @lunarfront/shared schemas and business logic
• Native Bluetooth for card reader pairing
• Native camera for faster barcode scanning
• Requires Apple Developer ($99/year) and Google Play ($25 one-time)
• Only worth it if PWA limitations become blockers (Bluetooth, offline, performance)

3. Shared Infrastructure

All frontends share:

Layer	Package	What it provides
Validation	@lunarfront/shared	Zod schemas — same validation client and server
Types	@lunarfront/shared	TypeScript interfaces for all domain entities
Business logic	@lunarfront/shared	Formatters, calculators, state normalization
API	Backend REST	Same endpoints, same auth, same response format
Auth	JWT	Same token works across all frontends
Permissions	RBAC	Same permission checks — POS user doesn't need admin access

This means:

• A bug fix in a Zod schema fixes validation everywhere
• A new API endpoint is immediately available to all frontends
• No data format translation between frontends
• One test suite covers the API regardless of which frontend calls it

4. Permission Mapping

Different frontends surface different permissions:

Permission	Admin	POS	Floor
accounts.view/edit/admin	Yes	View only (customer lookup)	View only
inventory.view/edit/admin	Yes	View only (product search)	Full access
pos.view/edit/admin	Reports only	Full access	Mobile POS mode
rentals.*	Yes	Process returns	No
lessons.*	Yes	No	No
repairs.*	Yes	Intake only	No
vault.*	Yes	No	No
users.*	Yes	No	No

The backend enforces permissions regardless — the frontend just decides what to show.

5. Offline Strategy

Offline support is critical for POS (network drops) and Floor (dead zones in warehouse).

POS offline:

• Cache product catalog in IndexedDB (refresh periodically)
• Queue transactions locally when offline
• Process card payments when back online (or show "cash only" mode)
• Sync queue when connection restores
• Visual indicator: "Offline — transactions will sync when connected"

Floor offline (inventory):

• Cache current inventory counts
• Store count entries locally
• Sync on reconnect
• Conflict resolution: last-write-wins with audit log of discrepancies

Admin:

• No offline support needed. Back-office work requires connectivity.

6. Deployment

Frontend	Hosting	Notes
Admin	Same server as backend (Caddy/nginx serves static files)	Single origin, no CORS
POS	Same server or dedicated POS terminal	Kiosk mode browser, auto-launch on boot
Floor	PWA from same server, or App Store	Phone/tablet accesses over store WiFi or cellular

For on-prem: all frontends are served from the same LunarFront server. One box, one URL, multiple apps at different paths (/admin, /pos, /floor).

7. Implementation Order

1. Admin UI — current, continue until core management is complete
2. POS UI — next major effort after admin is stable. This is the revenue-critical surface.
3. Floor App (Inventory mode) — PWA first. Enables stock receiving and cycle counts.
4. Floor App (Mobile POS mode) — add-on to floor app. Trade show / floor sales.
5. Floor App (Native) — only if PWA hits limitations. Bluetooth reader, performance, offline.

Each frontend is independently deployable. Stores can run just Admin + POS if they don't need mobile inventory. Modules control which features are available, not which frontends are installed.