Everything needed to set up, operate and deploy PivotPOS.

Set up a business

From onboarding to the first successful sale.

• Create the business and owner, verify email, then complete country, currency, timezone, address and business email.
• Upload the required logo, choose a theme color, configure tax and receipt settings, then create branches.
• Create roles before staff, register every POS device, add products and stock, configure printers, and complete the first online sync.
• Open a trading session and test cash settlement, receipt printing, stock reduction, dashboard totals and zero pending sync.

Users, roles and devices

Give each person only the access required for their job.

• Waiters normally create/update their own table orders and send items to preparation stations.
• Cashiers normally view orders, process payment and print receipts; day start/end is a separate permission.
• Managers receive controlled void, reports, table override and host-takeover permissions.
• A POS installation must be registered to the same tenant and branch before PIN login and synchronization.

Retail and general stores

Catalog, barcode, customers, stock and final-receipt checkout.

• Create categories and brands, then products with SKU/barcode, price, tax, opening stock and reorder level.
• Capture customer name, email and phone when available so receipts and order history remain connected.
• Retail checkout uses cash, card or transfer and prints a final receipt after approved settlement.
• The retail interface does not expose restaurant bill, table, split or merge terminology.

Restaurant, lounge and bar

Table ownership, waiter ordering, station printing and cashier settlement.

• The waiter opens an available table, adds quantities and notes, and sends routed items to kitchen, bar, lounge or custom stations.
• The cashier can access all tables, process split/merge/move actions, settle the approved payment and print the final receipt.
• Repeated products increase quantity; settled or voided orders release the table across LAN clients.
• Trading sessions may cross midnight and a branch may run more than one session in a calendar day.

Hotel and hospitality

Hospitality ordering, outlets, service areas and reservations.

• Use rooms/service areas, multi-outlet printer routing, hospitality reservations and public ordering.
• Reservation rules can be flat or per-person and may require a deposit.
• PMS folio posting, check-in/check-out and channel manager functions require a separate controlled integration.

Pharmacy, salon and services

Expiry-aware inventory and appointment-based services.

• Pharmacy batches record lot, received quantity and expiry date; legal controlled-drug workflows remain jurisdiction-specific.
• Appointments schedule a service and staff member and prevent overlapping active appointments.
• A reservation holds capacity and may take a deposit; an appointment schedules staff/service delivery.

Business and platform administration

Keep tenant operations separate from software-owner control.

• Business Admin manages catalog, inventory, orders, customers, staff, roles, branches, devices, printers, local sync, reports, billing and settings.
• Platform Admin manages tenants, plan pricing/features, subscriptions, platform users, public content, payment configuration and error-alert policy.
• Private API documentation remains restricted at /api-docs; the operator handbook is public at /docs.

Offline and LAN sync

Sell locally, synchronize in order and protect against duplicates.

• SQLite saves order, items, payment and outbox event atomically. Never clear app data while pending events exist.
• One registered device is the active branch host. Clients exchange events and snapshots with it about every three seconds.
• The host assigns the authoritative sequence, exact event IDs are acknowledged, and cloud replay uses idempotent UUIDs.
• Reserve the host IP in the router, use a trusted subnet, disable guest/client isolation and protect LAN requests with the branch access key.

Thermal printing

Receipt and preparation routing over LAN, USB or supported transports.

• Network ESC/POS printers normally use TCP port 9100 and must be on the same reachable subnet as the POS.
• RECEIPT prints the customer copy; preparation stations print matching item lines; ALL is a deliberate backup route.
• Multiple printers can share a dynamic station such as GRILL, OUTDOOR_BAR or VIP_LOUNGE.
• A print failure is logged locally and must not change the financial state of an accepted order.

nc -vz 192.168.1.242 9100
printf '\x1b@\nPIVOTPOS TEST\n\n\n\n' | nc 192.168.1.242 9100

Run locally

Docker PostgreSQL, Fastify API, Next.js web and Flutter POS.

• Docker publishes PostgreSQL on 127.0.0.1:5433. The API runs on 8000 and the web app on 3000.
• Use the Flutter helper scripts for macOS and physical Android so local API candidates are selected correctly.
• 127.0.0.1 on a physical phone is the phone itself; use the computer LAN address or ADB reverse.

docker compose up -d postgres
cd apps/api && npm install && npm run db:generate && npm run db:migrate && npm run db:seed && npm run dev
cd ../admin && npm install && npm run dev
cd ../pos && ./scripts/run_android_local.sh DEVICE_SERIAL

Deploy managed or on a VPS

Vercel + Render + Neon, or Docker Compose behind TLS.

• Managed staging uses Vercel for Next.js, Render for Fastify and Neon for PostgreSQL.
• A VPS should use Ubuntu LTS, Docker, a TLS reverse proxy, firewall rules, off-server backups and a private/managed PostgreSQL database.
• Run prisma migrate deploy in staging/production; never run prisma migrate dev against production.
• Build each Flutter release with the production HTTPS API URL and keep signing keys in secure backup.

API and security

JWT sessions, tenant scope, permissions, registered devices and idempotency.

• Protected requests use Bearer access tokens. Refresh once after 401; repeated 401 requires a new login.
• 400 is validation, 402 plan access, 403 permission/device/network denial, 409 state conflict and 500 unexpected server failure.
• The API owns tenant scope, validates payloads, rate-limits authentication and verifies payment webhooks.
• Use docs/openapi.yaml for the machine-readable contract and the private /api-docs page for the owner reference.

curl -X POST http://127.0.0.1:8000/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"owner@example.com","password":"Strong-password-123"}'

Testing and release acceptance

Verify the complete business flow before onboarding a customer.

• Test open/close session, cash/card/transfer, void permissions, stock, customers, online orders and notifications.
• For hospitality, test table locks, routing, same-item quantities, split/merge/move, settlement and QR/reservations.
• Turn internet off while keeping LAN active, place an order, restore internet and confirm pending count clears without duplicates.
• Test printer off/on recovery, correct cashier/date/currency/payment fields and enough trailing paper before cut.