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.

Key screens:

1. Lock screen — numeric keypad, current time, store name
2. Sale screen — product search (left), cart (right), totals + pay button (bottom)
3. Payment screen — amount due, payment method selection, card terminal status, change calculation
4. Return/exchange screen — lookup original transaction, select items, process refund
5. Drawer management — open session, cash drops, close session with counts

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

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.