# Go Past Earth — Overhead and Operations (OAO)

**Complete platform documentation for the Business OS**

**Last updated:** April 2026  
**Purpose:** Full technical documentation of the entire platform — server, databases, multi-tenancy, backend, frontend, and every core system. Use this when chat context is lost or when onboarding developers.

---

## Developer Quick Reference

| Need | Go To |
|------|-------|
| **Stack layers & wiring (orientation)** | [00-master-map.html](./00-master-map.html) |
| **Full-stack diagrams (clients → API → DB → Bridge)** | [30-full-stack-architecture.html](./30-full-stack-architecture.html) · [30 — MD companion](./30-FULL-STACK-ARCHITECTURE.md) |
| PM2, hosting, MySQL env (readable in browser) | [01-infrastructure.html](./01-infrastructure.html), [index.html](./index.html#operations-pm2-db) |
| Backend route mounts & middleware | [Appendix A](./APPENDIX-A-COMPLETE-ROUTE-TABLE.md) |
| POS flow (cart → tender → finalize), **register/shift**, PIN + `localStorage` | [Appendix B](./APPENDIX-B-COMPLETE-POS-FLOW.md), [06 — POS Systems](./06-POS-SYSTEMS.md), HTML [06](./06-pos-and-invoicing.html) |
| POS device registry, fuel/forecourt, posModules metadata | [13-bridge-and-devices.html](./13-bridge-and-devices.html), [06](./06-pos-and-invoicing.html); UI path `/admin/devices/manager` |
| POS offline queue, IndexedDB, idempotency | [14 — Frontend (HTML)](./14-frontend.html), [Appendix: Data Flows](./appendix-data-flows.html) |
| Tenant signup & provisioning | [Appendix C](./APPENDIX-C-COMPLETE-TENANT-PROVISIONING-FLOW.md) |
| Login, session, tenant resolution | [Appendix D](./APPENDIX-D-COMPLETE-AUTH-FLOW.md) |
| Audit logs, taxonomy, scopes | [20 — Audit](./20-AUDIT.md), [HTML](./20-audit.html) |
| **HTTP method + path catalog** (POS, register, signage, audit, …) | `docs/API-ENDPOINTS-CATALOG.md` · static [api-explorer.html](./api-explorer.html) · Admin `/admin/api-reference` (cross-check [Appendix A](./APPENDIX-A-COMPLETE-ROUTE-TABLE.md)) |
| Database tables & columns | [Appendix E](./APPENDIX-E-DATABASE-SCHEMAS.md) |
| Frontend routes & components | [Appendix F](./APPENDIX-F-FRONTEND-ROUTE-TREE.md) |
| Backend models & tables | [Appendix G](./APPENDIX-G-MODELS-INDEX.md) |
| **Small farm / local producer** (inventory + storefront + POS hub) | [29 — MD](./29-SMALL-FARM-PRODUCER.md) · [HTML](./29-small-farm-producer.html); UI: **Apps → Farm & producer** → `/admin/farm-producer`; signup category `farm` |

---

## What Go Past Earth Is

Go Past Earth (originally PAWSPOS) is a **multi-tenant Business OS platform** — a sophisticated alternative to Square, Stripe, PayPal, and a direct competitor to Lightspeed. We enable any business (restaurants, retail, salons, professional services, etc.) to run their operations on our hosted stack:

- **Point of Sale** (Standard, Modern, Mobile, Kiosk, Bar)
- **Kitchen Display System (KDS)**
- **Inventory** (multi-domain, variations, serials, kits)
- **Invoicing** (core of all money movement)
- **Cryptocurrency** (DOGE, LTC, BTC — non-custodial)
- **HR & Payroll** (time tracking, timesheets, payroll runs)
- **Business Analytics** (sales, staff, customer, trends)
- **Tickets & Appointments**
- **Floor Design / Seating Layouts**
- **Gift Cards & Loyalty**
- **Storefront**
- **Bridge** (device discovery, printers, KDS, cloud sync)
- **Digital signage** (in-venue ad catalog, display URLs, public player; optional bridge refresh) — HTML: [26-signage.html](./26-signage.html)

---

## Documentation Index

### Strategic (CEO-Level)
| # | Document | Description |
|---|----------|-------------|
| 00 | [CEO Strategic Overview](./00-CEO-STRATEGIC-OVERVIEW.md) | Business vision, competitive positioning, differentiators |

### Core Documentation
| # | Document | Description |
|---|----------|-------------|
| 01 | [Server & Deployment](./01-SERVER-AND-DEPLOYMENT.md) | PM2, Nginx, SSL, staging, Cloud SQL proxy, ports |
| 02 | [Databases & Multi-Tenancy](./02-DATABASES-AND-MULTI-TENANCY.md) | Master DB, tenant DBs, templates, schemas, provisioning |
| 03 | [Backend Architecture](./03-BACKEND-ARCHITECTURE.md) | Express, routes, middleware, services, auth |
| 04 | [Frontend & Public Site](./04-FRONTEND-AND-PUBLIC-SITE.md) | React apps, routes, layouts, API integration |
| 05 | [Invoicing System](./05-INVOICING-SYSTEM.md) | Core invoicing, invoices table, POS→invoice flow |
| 06 | [POS Systems](./06-POS-SYSTEMS.md) | StandardPOS, ModernPOS, MobilePOS, Kiosk, Bar, register |
| 07 | [Cryptocurrency](./07-CRYPTOCURRENCY.md) | DOGE, LTC, BTC, wallets, webhooks, non-custodial |
| 08 | [KDS & Kitchen](./08-KDS-AND-KITCHEN.md) | Kitchen Display, preparables, recipes, fire ticket |
| 09 | [Inventory](./09-INVENTORY.md) | Items, variations, domains, ledger, stock, vendors |
| 10 | [Floor Design & Seating](./10-FLOOR-DESIGN-AND-SEATING.md) | Seating layouts, floor plans |
| 11 | [HR & Payroll](./11-HR-AND-PAYROLL.md) | Employees, time tracking, payroll, benefits |
| 12 | [Business Analytics](./12-BUSINESS-ANALYTICS.md) | Reports, dashboard, sales, staff, customer analytics |
| 13 | [Tickets & Appointments](./13-TICKETS-AND-APPOINTMENTS.md) | Service desk, ticket workflows, appointments |
| 14 | [Bridge & Devices](./14-BRIDGE-AND-DEVICES.md) | Bridge WebSocket, device discovery, printers, C# bridge |
| 15 | [Other Systems](./15-OTHER-SYSTEMS.md) | Gift cards, loyalty, storefront; audit deep-dive [20 — Audit](./20-AUDIT.md); webhooks |
| 29 | [Small farm & local producer](./29-SMALL-FARM-PRODUCER.md) · [HTML](./29-small-farm-producer.html) | Farm stand stack: signup `farm`, nav theme, Apps hub `/admin/farm-producer`, Inventory + Storefront + POS |

### Appendices (Developer Deep-Dive)
| # | Document | Description |
|---|----------|-------------|
| A | [Complete Route Table](./APPENDIX-A-COMPLETE-ROUTE-TABLE.md) | Every backend route mount, middleware, order |
| B | [Complete POS Flow](./APPENDIX-B-COMPLETE-POS-FLOW.md) | Register/shift + PIN persistence, then cart → tender → finalize (step-by-step) |
| C | [Complete Tenant Provisioning](./APPENDIX-C-COMPLETE-TENANT-PROVISIONING-FLOW.md) | Signup → provisioning (exact steps, tables) |
| D | [Complete Auth Flow](./APPENDIX-D-COMPLETE-AUTH-FLOW.md) | Login, session, tenant resolution, POS register |
| E | [Database Schemas](./APPENDIX-E-DATABASE-SCHEMAS.md) | Tables, columns, master vs tenant |
| F | [Frontend Route Tree](./APPENDIX-F-FRONTEND-ROUTE-TREE.md) | All frontend paths, layouts, components |
| G | [Models Index](./APPENDIX-G-MODELS-INDEX.md) | Backend models, tables, key fields |

---

## How to Use This Documentation

**CEO / Business Stakeholders:** Start with [00 — CEO Strategic Overview](./00-CEO-STRATEGIC-OVERVIEW.md). It explains the product vision, competitive positioning, and differentiators. For **prep vs suite-scale competitors** (fundraising, enterprise conversations, roadmap anxiety), use [28 — Competitive positioning & ICP workbook](./28-COMPETITIVE-POSITIONING-AND-ICP-WORKBOOK.md) or the browsable [HTML chapter](./28-competitive-positioning-and-icp-workbook.html). For **farm stands and local producers** (same stack, dedicated onboarding), use [29 — Small farm & local producer](./29-SMALL-FARM-PRODUCER.md) or [HTML](./29-small-farm-producer.html).

**Developers / Technical Onboarding:**  
1. Open [30 — Full-stack architecture (HTML)](./30-full-stack-architecture.html) for **one-page diagrams** of how everything connects; keep [00 — Master Map (HTML)](./00-master-map.html) for the layered narrative.  
2. Read [01 — Server & Deployment](./01-SERVER-AND-DEPLOYMENT.md) and [02 — Databases & Multi-Tenancy](./02-DATABASES-AND-MULTI-TENANCY.md) for infrastructure.  
3. Read [03 — Backend Architecture](./03-BACKEND-ARCHITECTURE.md) for routes, middleware, services.  
4. Use the **Appendices** as reference when implementing or debugging:  
   - Need a specific route? → Appendix A  
   - Tracing POS flow? → Appendix B  
   - Understanding signup? → Appendix C  
   - Auth/session issues? → Appendix D  
   - Schema questions? → Appendix E  
   - Frontend routing? → Appendix F  
   - Model/table lookup? → Appendix G  

**AI / Context Recovery:** When chat context is lost, read this INDEX, **[chapter 30 diagrams](./30-full-stack-architecture.html)**, and the relevant appendices to restore full platform understanding.

---

## Quick Reference

### Key Paths (staging/production)

| 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 |
| `/home/pawspos/app/infrastructure` | PM2, Nginx, SSL |
| `/home/pawspos/app/logs` | PM2 logs |

### Key URLs

| URL | Purpose |
|-----|---------|
| `https://staging.gopastearth.com` | Staging |
| `https://staging.gopastearth.com/signup` | Tenant signup |
| `https://staging.gopastearth.com/login` | Platform login |
| `https://staging.gopastearth.com/dashboard` | Tenant dashboard |
| `https://staging.gopastearth.com/pos` | POS |
| `https://staging.gopastearth.com/master-admin` | Master admin |

### PM2 Commands

**Full stack config:** `infrastructure/ecosystem.production.config.js` (backend + frontends + optional cloud-sql-proxy). **Minimal:** root `ecosystem.config.js` (backend only; DB often from `backend/.env`). **Helper scripts:** `./restart-backend.sh`, `./restart-frontend.sh`, `./restart-all.sh`.

```bash
pm2 status
pm2 restart all
pm2 restart pawspos-backend --update-env   # after changing env in ecosystem file
pm2 logs pawspos-backend
pm2 save
```

**Staging / DB:** See `infrastructure/STAGING-SETUP.md` (SSL, CORS). Master DB name and tenant DB prefixes: `MYSQL_MASTER_DATABASE`, `MYSQL_TENANT_DB_PREFIX` — see [02-databases.html](./02-databases.html). Platform catalog table: `backend/migrations/create-platform-product-catalog.sql`.

---

## Related Docs (pre-OAO)

- `docs/HOW-IT-ACTUALLY-WORKS.md` — Traced request flows
- `docs/GOPASTEARTH-HOLISTIC-OVERVIEW.md` — Product overview
- `docs/API-ENDPOINTS-CATALOG.md` — API catalog
- `docs/FRONTEND-ROUTE-API-MAP.md` — Frontend→API map
- `docs/FULL-WIRING-MAP.md` — Full wiring
- `docs/TEMPLATE-DATABASE-SYSTEM.md` — Template DBs