Go Past Earth — DocHub
A complete visual hierarchy and flowchart breakdown of the Business OS. Use this to verify architecture, develop in the right place, and avoid catastrophic changes on a live multi-tenant system.
/oao/). This DocHub is the
orientation + correctness map; OAO is the chapter detail.
When they conflict, verify against live code on this server and update both.
One-page system picture
Outside → inside. Every feature hangs off this skeleton.
flowchart TB
subgraph PRESENTATION["1 · Presentation"]
FE["frontend/ — Dashboard · POS · Admin · HR · Master Admin"]
PS["public-site/ — Marketing · Store · Barcode · Signup"]
DEVUI["Kiosk · Mobile · KDS · Signage player"]
end
subgraph EDGE["2 · Edge"]
NGX["Nginx TLS · staging.gopastearth.com"]
end
subgraph APP["3 · Application"]
PM2["PM2: pawspos-backend cluster :4000"]
MW["sessionAuth · tenantResolver · deviceAuth · featureGate"]
end
subgraph DOMAIN["4 · Domain services"]
POS["POS · Cart · Register"]
INV["Core Invoicing"]
OPS["Inventory · KDS · Catalog"]
PPL["HR · Tickets · Appointments"]
MON["Crypto · Gift · Loyalty · Storefront"]
PLAT["Master Admin · Platform Catalog · Audit"]
end
subgraph DATA["5 · Data"]
MASTER["Master DB — Tenants · Catalog · routing"]
TMAIN["dev-{slug} — ops"]
TANAL["dev-analytics-{slug}"]
THR["dev-hr-{slug}"]
end
subgraph INT["6 · Integration"]
BR["bridge/ + Windows C#"]
HW["Printers · KDS LAN · Devices"]
end
FE --> NGX
PS --> NGX
DEVUI --> NGX
NGX --> PM2
PM2 --> MW
MW --> POS & INV & OPS & PPL & MON & PLAT
POS --> INV
INV --> TMAIN
OPS --> TMAIN
PPL --> TMAIN & THR
MON --> TMAIN
PLAT --> MASTER
POS --> TMAIN
INV --> TANAL
BR --> PM2
BR --> HW
Canonical request path: browser → Nginx → Express middleware → domain service → tenant or master DB. Bridge attaches at the edge of the LAN.
Chapter map
Work through these in order when onboarding or before a major change.
Expanded mind map
Roomy branch-by-branch product map — overview, then Platform, Commerce, Operations, People, etc.
Full product hierarchy
Implementation tree with file paths and where new work should hang.
Deployment stack
This box, PM2, Nginx, Cloud SQL, domains, what is “prod” today.
Data plane
Master + per-tenant main / analytics / HR. Isolation model and catalog home.
Request & auth flow
Session cookies, tenant resolution, roles, device secrets, feature gates.
Money spine
Register → cart → tender → finalize → Core Invoicing. Storefront reuses POS.
Feature map
All modules with primary routes, APIs, code anchors, status tags.
Clients & surfaces
Who uses which URL: staff, customer, employee, kiosk, master admin, public.
Devices, KDS, signage
Bridge, kitchen tickets, seating tie-in, what signage is (and is not) yet.
UPC / barcode product
Master GTIN DB: tenant POS/inventory benefit + public teaser + paid external API roadmap.
Apps & verticals
Farm hub, themes, theater path, expansion pattern via apps.
POS & Mobile POS
Full inventory: entry routing, Modern vs Mobile parity, /api/pos spine, stubs & naming traps.
Floor map · KDS · GPE Signage
Seating designer, kitchen tickets, venue displays — vision for multi prep-screen seat relay.
Tickets & appointments
Service desk, public feedback portal, stylists/booking, appointment→ticket link.
Gift · loyalty · membership
Stored-value cards, points/tiers as membership, POS redeem/earn, API map & debt.
Customers & storefront
CRM, customer portal, online store, POS-backed checkout, guest-checkout caveats.
Bridge & devices
Device registry, secrets, locations, on-prem bridge, printers, signage relay.
Crypto & payments
Non-custodial crypto, providers, legacy off, what real e-com still needs.
HR & payroll
HR DB, team vs employees, timeclock, PTO, payroll, employee portal.
Hub & reports
Business Hub APIs, sales report tree, main vs analytics DB caution.
Tax · receipts · notify
Sales tax, receipt templates/email/SMS/print, mail settings.
Master Admin
Platform ops: tenants, provision, catalog, health — master_admin only.
Inventory
Domains, ledger, POs, serials/kits, POS consumption, unit UI gaps.
Coverage & remaining
Matrix of what we mapped, thin areas, stubs, debt — and what to build next.
Auditability & invoicing
Owner sales truth, Core Invoicing, ticket bills, audit logs, maturity & roadmap.
Core Invoicing readiness
Real-world multi-business deep review: live schema, POS/ticket flows, void/refund, P0 gaps.
Tenant email ops
Per-business SMTP, platform fallback, receipts/refunds/store credit, email_log.
Payment rails matrix
Cash/card/gift/loyalty + DOGE/LTC/BTC parity — all tenders → Core Invoicing.
Gaps & audit status
What was fixed, what remains open, what is roadmap not bug.
How we develop
Safe change rules on a live box with no easy rollback (until git lands).
Git & domains
dochub + gperep DNS, SSL, first real repository plan.
Non-negotiable design truths
| Truth | Implication for development |
|---|---|
| Invoicing is the money backbone | New payment paths must write or link Invoices — do not invent parallel ledgers. |
| DB-per-tenant isolation | Never share operational tables with a tenant_id shortcut; resolve DB via tenant middleware. |
| Master owns platform catalog | Barcode enrichment is master-scoped; tenants copy metadata into their own items/pricing. |
| Staging is the live product | Treat staging.gopastearth.com as production until a real prod cutover. |
| Capable backend, thin UI is a pattern | Before “rewrite,” check if schema/API already exists and only UI is missing. |
| OAO + AUDIT-FINDINGS over folklore | Root *COMPLETE.md files and old docs/ are historical; verify when unsure. |
Live runtime (this server)
flowchart LR
U[Users / devices] --> D{Domain}
D -->|staging.gopastearth.com| STG[Nginx staging]
D -->|dochub.gopastearth.com| DOC[Nginx DocHub static]
D -->|gperep.gopastearth.com| GIT[Gitea · gopastearth repo]
STG --> BE[backend :4000 ×2]
STG --> FE[frontend Vite :5173]
STG --> PUB[public-site dist]
BE --> SQL[(Google Cloud SQL MySQL)]