Go Past Earth — Platform Documentation

Complete technical documentation • CEO to Developer • Updated July 2026

CEO Summary

Go Past Earth is a multi-tenant Business Operating System — not “just a POS.” The same stack covers money movement (sales, payments, invoicing, crypto), people (HR, payroll, timeclock, employee portal), operations (inventory, KDS, recipes, seating layouts), customer touchpoints (storefront, tickets, appointments, loyalty, gift cards), and governance (audit, tax, receipts, reporting, master admin). Differentiators include non-custodial cryptocurrency, tenant isolation, and Bridge-connected on-premises devices.

Key metrics: Tenant count, transaction volume, uptime, feature adoption. Dependencies: MySQL, Nginx, PM2; Cloud SQL Proxy is optional when the app uses a direct database host. If the backend is down, all tenant operations stop.

Start here: Master Map — one-page layered view of the stack (experience → edge → API → services → databases → Bridge/devices) with links into each chapter. 30 — Full-stack architecture — dedicated page of Mermaid diagrams (deploy, data plane, middleware, API domains, clients, auth modes) for developers and AI context recovery. 31 — Domains & Beacon — product hostnames (dashboard · pos · kds · beacon, API on main domain, Beacon rebrand plan. Platform Features — full business-facing list of everything you can sell and demo. 28 — Competitive & ICP (HTML) / Markdown — suite-scale comparison lenses, ICP template, daily workflow matrix, gap tags. 29 — Small farm & producer (HTML) / Markdown — farm-stand onboarding (signup, nav theme, Apps hub, same Inventory + Storefront + POS stack).

Documentation truth: Chapters 01–26, vertical playbook 29, and the appendices describe what is in the codebase and how it is wired. Some enterprise-grade controls (e.g. every POS action behind fine-grained RBAC) are partially modeled or in progress — see 25 — Platform Coverage for scope and honesty about production readiness.

Platform Architecture

In-venue displays are product-named Beacon (Beacon Screen); technical chapter still 26 — Signage. Target hosts and API-on-apex rules: 31 — Domains & Beacon. Deploy diagrams: 30 — Full-stack architecture.

flowchart TB subgraph client [Client layer] Browser[Browser / Dashboard] PublicSite[Public site] OffQ[(IndexedDB offline queue)] end Browser -.-> OffQ subgraph cloud [Cloud] Nginx[Nginx] Express[Express API] MySQL[(MySQL)] end subgraph onprem [On-premises] Bridge[Bridge C# / Node] Devices[Printers / KDS / LAN] end Browser --> Nginx PublicSite --> Nginx Nginx --> Express Express --> MySQL Express -->|WebSocket| Bridge Bridge --> Devices

What the Platform Provides

Point of Sale — Standard, Modern, Mobile, Kiosk, Bar; browser offline queue with idempotent replay (14, 06); Modern POS optional vertical modules (e.g. forecourt / fuel via Devices.metadata.posModules and 13)
Kitchen Display System (KDS) — Orders to kitchen, preparables, recipes
Inventory — Multi-domain, variations, serials, kits, vendors
Invoicing — Core of all money movement
Cryptocurrency — DOGE, LTC, BTC — non-custodial
HR & Payroll — Time tracking, timeclock, timesheets, payroll runs, employee portal
Business Center — Unified hub: analytics, payments, operations, timeclock, reports
Business Analytics — Sales, staff, customer, trends
Public Ticket Portal — Customers submit tickets without login
Tickets & Appointments — Service desk, public booking
Floor Design — Seating layouts
Gift Cards & Loyalty
Storefront
Farm & local producer — Same stack with dedicated signup, nav theme, and Apps → Farm & producer hub (29)
Bridge — Device discovery, printers, KDS, cloud sync
Compliance & comms — Audit logging (API + admin UI), tax settings, email/SMS

Real-World Business Transaction Scope

From a transaction lifecycle perspective, a business typically needs: sell → tender → settle → record → report → prove (receipt/audit). This platform maps those needs to concrete systems:

Business need	Where it lives (docs)
Sell in person (any mode)	06, 14
Take payment (card, cash, crypto, gift card, loyalty)	04, 06, 17, 18
Tax-correct totals	21, 06
Inventory impact & costing	07
Farm stand / local producer (vertical)	29 — Small farm & producer → 07, 19, 06
Kitchen / fulfillment	09 (KDS API, admin routing, POS tickets)
Floor & seating	09 (seating layouts)
Staff time & pay	10, 16
Proof & disputes	22, 20
Owner visibility	12, 16
In-venue digital menus / promo screens	26 — Signage, 13 (bridge notify)
Full system map	25

Platform Product Catalog (Barcode) — Implemented

A platform-owned reference table lives on the master database: platform_product_catalog (GTIN/barcode → title, brand, image, JSON attributes). Tenants keep their own stock and pricing in tenant DBs; this layer enriches scans when no local match exists.

API (tenant): GET /api/platform-catalog/lookup?barcode=... — session + tenant; used by POS and inventory (no inventory feature flag required).
API (master admin): /api/master-admin/platform-catalog — list, upsert, patch, activate/deactivate.
UI: Inventory ItemsPage + ItemWizardSimple prefill; ModernPOS adds synthetic line from catalog when POS catalog has no match; Master Admin /master-admin/platform-catalog.
Docs: 02 — Databases (table + env), 07 — Inventory, 06 — POS, 24 — Master Admin, 01 — Infrastructure (PM2 + MySQL env).

Roadmap: CSV import, partner feeds, optional external API revenue — same table and admin surface extend naturally.

Operations: PM2 & databases

The live server runs the API and Vite apps under PM2 (infrastructure/ecosystem.production.config.js). MySQL hostnames and master vs tenant DB names come from env (see 01 — Infrastructure and 02 — Databases). Staging-specific steps (SSL, CORS, verification script) are in infrastructure/STAGING-SETUP.md.

Task	Typical command / reference
Status	`pm2 status`
Restart backend after code deploy	`pm2 restart pawspos-backend` or `./restart-backend.sh`
Reload env from ecosystem file	`pm2 restart pawspos-backend --update-env`
Apply master DB migration (catalog)	SQL file `backend/migrations/create-platform-product-catalog.sql` against `MYSQL_MASTER_DATABASE`
Logs	`pm2 logs pawspos-backend --lines 50`, files under `/home/pawspos/app/logs/`

Quick Reference

Need	Go To
Backend routes & middleware	Route Table, Middleware, Controllers
POS flow (cart → finalize)	Appendix: Data Flows
Tenant signup & provisioning	02 — Databases
Login, session, tenant resolution	05 — Auth & Tenancy
Database tables & columns	02 — Databases, Appendix: Models
Frontend routes & components	14 — Frontend
KDS, kitchen routing (admin)	09 — KDS & Kitchen, Appendix: Data Flows
Business Center, timeclock	16 — Business Center
Employee portal, pay stubs, taxes	10 — HR & Payroll
Public customer ticket portal	11 — Tickets & Appointments
Gift cards, loyalty, storefront, audit, tax, receipts, email/SMS, master admin	15 — Other Systems (hub) → 17–24
Barcode scanning, future master product catalog	07 — Inventory, Platform catalog roadmap
End-to-end coverage map	25 — Platform Coverage
Stack layers & wiring (orientation)	Master Map
Full product catalog (sales & ownership)	Platform Features
Competitive positioning, ICP, gap tagging (Lightspeed-class prep)	28 — Competitive & ICP
Farm & local producer (signup, hub, workflow)	29 — Small farm & producer, 15 — Other Systems (hub table)

Key Paths & URLs

Path	Purpose
`/home/pawspos/app`	App root
`/home/pawspos/app/backend`	Express API
`/home/pawspos/app/frontend`	Dashboard SPA
`/home/pawspos/app/public-site`	Marketing/signup
https://staging.gopastearth.com	Staging
https://staging.gopastearth.com/signup	Tenant signup
https://staging.gopastearth.com/pos	POS
`…/pos/kitchen` and `?station=`	Kitchen Display (KDS)
`…/admin/kitchen-displays`	Admin: category → station routing, KDS toggles
https://staging.gopastearth.com/business-hub	Business Center dashboard
`…/admin/devices/manager`	Device registry (POS metadata, forecourt/fuel toggle)
https://staging.gopastearth.com/employee-portal	Employee portal (HR self-service)
https://staging.gopastearth.com/{tenant}/public/ticket	Public customer ticket portal
`/admin/signage`	Admin: folders, ads, displays, bridge notify
`/{tenantSlug}/signage/{displaySlug}`	Public fullscreen player (optional `?reloadSec=60`)

Platform Coverage Map

25 — Platform Coverage is the master index from capability to API mount and documentation chapter. Use it for audits, onboarding, and to verify nothing is missing after shipping new features. Platform Features is the narrative sales / CEO checklist of the same surface area. 28 — Competitive & ICP is the dedicated chapter for suite-scale comparison, ICP, and workflow gap tags. 29 — Small farm & producer is the vertical playbook for farm stands and local producers (same stack, dedicated onboarding).

How to Use This Documentation

New here: Open Master Map first — it shows the platform as stacked layers (experience → edge → API shell → domain services → databases → Bridge) and links into the chapters. For diagrams of how everything wires together, use 30 — Full-stack architecture. For a single scroll of capabilities to sell or onboard, use Platform Features. Before enterprise or fundraising conversations, read 28 — Competitive & ICP. For farm stands and local producers, read 29 — Small farm & producer (also in the left nav under Overview).

CEO / Ownership: Each page starts with a CEO Summary — business value, metrics, risk. Read the summaries to understand what each system enables.

Developers: Each page includes architecture diagrams (Mermaid) and developer detail — file paths, tables, APIs. Use the appendices for route tables, models, and data-flow traces.

Data flows: See Appendix: Data Flows for top-to-bottom and bottom-to-top traces of key operations (POS sale, login, signup).