31 — Product domain surfaces & Beacon

Target hostname map · API on apex · Beacon rebrand · phased cutover · July 2026

Design principles

1. One money spine, many windows. Subdomains are presentation shells. Core Invoicing, inventory, tenants, and auth remain one backend.
2. API lives on the main domain. Browsers and devices call https://gopastearth.com/api/… (and related service paths), not api.pos.gopastearth.com.
3. Subdomains are surface routers. Each host loads the SPA entry that belongs there and may deep-link into path routes for compatibility.
4. Cookies span the product family. Session cookie domain = .gopastearth.com so dashboard ↔ POS ↔ KDS share login when appropriate.
5. Beacon is the product name for signage. Code may keep signage packages for a while; user-facing strings and hostnames use Beacon.

Target domain map

Optional later hosts (not required for first cut)

API & shared services on the main domain

All surface subdomains are API consumers. They do not host Express.

Frontend env (target)

# Product SPAs (dashboard / pos / kds / beacon builds)
VITE_API_BASE_URL=https://gopastearth.com
# or relative only if SPA is reverse-proxied with /api on same host (staging all-in-one)

# Cookie / CORS (backend)
COOKIE_DOMAIN=.gopastearth.com
CORS_ORIGIN=https://dashboard.gopastearth.com,https://pos.gopastearth.com,https://kds.gopastearth.com,https://beacon.gopastearth.com,https://gopastearth.com,https://www.gopastearth.com,https://staging.gopastearth.com
SESSION_SAME_SITE=None   # if cross-site; or Lax if always same-site eTLD+1 with Domain=.gopastearth.com
SESSION_SECURE=true

Beacon (was: Signage / nSign-class service)

Beacon responsibilities

• Player host: fullscreen loop, public playlist fetch, optional ?reloadSec=, offline-friendly cache later
• Admin (on dashboard): folders, creatives (image/video/URL/HTML), named displays, bridge notify
• Bridge: optional signageUpdate → product docs call this “Beacon refresh push”

Deep technical behavior remains in 26 — Signage & Displays until that chapter is fully retitled; this chapter owns naming + host placement.

Surface → route ownership

Auth & tenant context across hosts

• Session cookie: Domain=.gopastearth.com, Secure, HttpOnly, path /
• CORS: allow product subdomains with credentials: true
• CSRF: keep existing same-site strategy; re-validate when SameSite=None
• Tenant header: continue X-Tenant-Slug / session tenant; Beacon player often tenant-in-URL (public playlist)
• Device auth: KDS / POS register may use device tokens independent of platform session — unchanged

Nginx sketch (target)

# Apex — marketing + API
server {
  server_name gopastearth.com www.gopastearth.com;
  location /api/   { proxy_pass http://127.0.0.1:4000; ... }
  location /auth/  { proxy_pass http://127.0.0.1:4000; ... }
  location /media/ { proxy_pass http://127.0.0.1:4000; ... }
  location /health { proxy_pass http://127.0.0.1:4000; }
  location /       { proxy_pass http://public_site_or_static; }
}

# Product shells — same frontend build or surface-specific builds
server {
  server_name dashboard.gopastearth.com pos.gopastearth.com
              kds.gopastearth.com beacon.gopastearth.com;
  # SPA fallback
  location / { proxy_pass http://127.0.0.1:5173; /* or static dist */ }
  # Optional: do NOT proxy /api here — force clients to apex (clear separation)
}

# Compat during migration
server {
  server_name staging.gopastearth.com;
  # Keep today's path-based all-in-one until cutover complete
}

TLS: wildcard *.gopastearth.com + apex, or individual certs via Certbot. Prefer wildcard for product subdomains.

DNS: A/AAAA for apex + each host (or CNAME to load balancer) → current edge IP.

Build / deploy strategy

Host-based entry (Option A) — logic sketch

const host = window.location.hostname;
if (host.startsWith('pos.'))     defaultRoute = '/pos';
if (host.startsWith('kds.'))     defaultRoute = '/pos/kitchen'; // confirm actual path
if (host.startsWith('beacon.'))  defaultRoute = beaconPlayerFromPath();
if (host.startsWith('dashboard.') || host === 'app.') defaultRoute = '/dashboard';
// API base always https://gopastearth.com (prod) or staging for QA

Phased delivery plan

Phase 0 — Document & decide (this chapter)

• Lock hostnames, Beacon naming, API-on-apex rule
• Inventory all absolute links that hardcode staging.gopastearth.com paths

Phase 1 — DNS + TLS + Nginx skeletons

• Create DNS records for dashboard, pos, kds, beacon (+ apex if not live)
• Wildcard or multi-SAN cert
• Nginx server blocks; initially all proxy to current SPA + still allow path mode on staging

Phase 2 — Auth hardens for multi-host

• COOKIE_DOMAIN=.gopastearth.com
• CORS allowlist of product hosts
• Frontend VITE_API_BASE_URL (or runtime config) pointing at apex
• Smoke: login on dashboard → open POS host still authenticated

Phase 3 — Surface defaults + Beacon rebrand (UI)

• Host-based default routes
• Nav: “Beacon”; page: “Beacon Screen”; player URLs show beacon host in admin copy
• Redirect helpers: /admin/signage → /admin/beacon (alias)

Phase 4 — Storefront & public on apex

• Marketing + /{slug}/store (or shop subdomain later)
• Signup completion → dashboard host

Phase 5 — Deprecate path-only mental model on staging

• staging remains all-in-one for QA
• Production traffic prefers product hosts
• Update bridge docs, device bookmarks, Beacon display URL generator

Cutover checklist

Non-goals (for this initiative)

• Splitting databases per surface
• Separate backend processes per subdomain (unless scale forces it later)
• Replacing Bridge with a cloud-only LAN story
• Forcing storefront onto shop. before apex path works
• Immediate full rename of every signage code symbol (UI + host first; code aliases second)

Related docs

Glossary snippet