# Go Past Earth — Full-stack architecture (diagram companion)

**Companion to:** [30-full-stack-architecture.html](./30-full-stack-architecture.html) (browser Mermaid diagrams)

**Last updated:** April 2026

This Markdown file summarizes what the HTML page diagrams depict. The **canonical interactive diagrams** are on the HTML page (Mermaid renders in the browser).

---

## Platform identity

- **Product:** Go Past Earth (Business OS). Codebase and repos historically used **PAWSPOS** / `pawspos` paths; production URLs use **gopastearth.com**.
- **Architecture:** Multi-tenant SaaS — one Express API, **per-tenant MySQL databases** for operational data, **master** database for tenants/platform identity/shared catalog.

---

## Diagram index (HTML page)

1. **Deployment & runtime** — Browser, Nginx, PM2 processes, where `frontend/dist` is served from, optional Vite dev servers, Cloud SQL proxy (optional).
2. **Data plane** — Master DB vs `{prefix}{slug}` main / HR / analytics DBs; `getTenantConnection` vs `multiDatabaseManager`.
3. **HTTP request path** — TLS → Nginx → Express middleware chain → tenant resolution → route mount → service → DB pool.
4. **Backend API surface (logical)** — Grouped routers: auth, POS, payments v1, inventory, HR, tickets, bridge, webhooks, static SPA fallback.
5. **Client applications** — Dashboard SPA routes, POS entry, public site, signage player, offline queue.
6. **Cross-cutting flows** — Session cookie, tenant headers/slug, register PIN auth (no platform session), Bridge WebSocket.

---

## Key code anchors

| Concern | Location |
|--------|----------|
| Express app, mount order | `backend/server.js` |
| Tenant DB pools | `backend/config/tenantDatabase.js` |
| HR / analytics DB name resolution | `backend/config/multiDatabaseManager.js` |
| Session + cookie | `backend/middleware/sessionAuth.js` |
| Tenant context | `backend/middleware/tenantResolver.js` |
| SPA static + `index.html` fallback | `backend/server.js` (`frontend/dist`) |
| Feature gating | `backend/middleware/featureGate.js`, `backend/config/planFeatures.js` |

---

## Related OAO chapters

- [00-master-map.html](./00-master-map.html) — Layered stack narrative
- [01-infrastructure.html](./01-infrastructure.html) — PM2, Nginx, SSL
- [02-databases.html](./02-databases.html) — DB naming and provisioning
- [03-backend.html](./03-backend.html) — Routes and middleware
- [05-auth-and-tenancy.html](./05-auth-and-tenancy.html) — Auth and isolation
- [Appendix A — Routes](./APPENDIX-A-COMPLETE-ROUTE-TABLE.md) — Exhaustive route list
- [INDEX.md](./INDEX.md) — Full doc map