Master Map — Layers & Wiring

One page to see how the stack fits together • April 2026

CEO Summary

This page is the orientation layer for the whole platform: what touches the customer, what routes traffic, what enforces security and tenancy, where business logic runs, and where data lives. Use it when onboarding, planning integrations, or explaining architecture without opening twenty chapters at once. Business value: faster decisions and fewer wrong assumptions about what depends on what.

For a single scroll of everything you can sell and demo (apps, money flows, HR, devices, etc.), use Platform Features. For end-to-end wiring diagrams (Nginx → Express → DBs → Bridge, plus API domain grouping), use 30 — Full-stack architecture.

How to read the stack

This is a classic layered architecture (outside → inside). Names below are the usual industry terms — nothing cute, just consistent vocabulary for docs and diagrams.

Layer	Role	What lives here
1 — Presentation	What users and visitors interact with	Browsers, SPAs, public marketing site, kiosk/register UIs
2 — Edge	TLS termination, routing, static assets	Nginx, HTTPS, reverse proxy to Node, optional caching
3 — Application	HTTP server, cross-cutting concerns, tenancy	Express, middleware chain, sessions, tenant resolution, authentication
4 — Domain	Business rules and feature modules	Route handlers, services: POS, payments, inventory, HR, tickets, crypto, webhooks, etc.
5 — Data	Persistent storage	MySQL: master DB (tenants, platform catalog) + per-tenant DBs + analytics DBs
6 — Integration	On-site devices and real-time links	Bridge, WebSockets, printers, KDS, local device sync

Typical request path: HTTPS traffic moves down presentation → edge → application → domain → data. Bridge and devices attach at the integration layer and talk to the same application and data tiers; they are not on every browser request path. Browser IndexedDB (pawspos_offline) holds the POS offline mutation queue in the presentation layer until replay to the API succeeds — see 14 — Frontend. Tenant isolation for MySQL is described in 02 — Databases.

Visual stack (outside → inside)

Read from top to bottom — that is the typical user request path.

1 · Presentation

Experience & surfaces

Dashboard SPA (frontend/), marketing / signup (public-site/), POS & Business Center routes, employee portal, public ticket portals.

14 — Frontend — SPA structure, POS modes, Admin vs Business Hub
13 — Bridge & Devices — device registry, posModules metadata
Home: Key Paths — URLs

2 · Edge

Edge & transport

Nginx fronts the API and static assets; HTTPS; proxy to Node (e.g. :4000). PM2 keeps processes alive in production.

01 — Infrastructure — Nginx, PM2, SSL, deploy

3 · Application

API server & cross-cutting concerns

backend/server.js — CORS, body parser, session store, then tenant resolver and auth middleware before any business route. This layer decides which database and which tenant context applies.

03 — Backend — middleware order, route groups
05 — Auth & Tenancy — sessions, headers, isolation
Appendix: Middleware

4 · Domain

Domain modules & services

Routers under backend/routes/ delegate to backend/services/ and controllers. Each feature area (POS, catalog, inventory, payroll, tickets, crypto, webhooks, …) owns its business rules and mostly persists to the tenant database (and sometimes the master DB for shared metadata).

06 — POS & Invoicing
04 — Payments Engine
07 — Inventory
25 — Platform Coverage — full capability map
Appendix: Route Table

5 · Data

Data plane

Master database: Tenants, Users (platform identity), platform_product_catalog, ticket metadata shared across tenants where modeled, etc. Per-tenant databases: {prefix}{tenantSlug} for app data; analytics DBs: {analyticsPrefix}{tenantSlug}.

02 — Databases — naming, provisioning, catalog table
Appendix: Models

6 · Integration

Bridge & devices

Bridge connects on-premises hardware to the cloud API over WebSockets — printers, KDS screens, device discovery, and signage refresh (signageUpdate events). Not on every request path, but on every physical fulfillment and many in-venue display paths.

13 — Bridge & Devices
26 — Signage & Displays
09 — KDS & Kitchen — cloud tickets, /api/kds, admin routing (/api/admin/kds)

Wiring diagram (request path)

flowchart TB subgraph L1[L1 Presentation] UI[Browser / SPA / Public site] SIG[Signage player fullscreen] IDB[(IndexedDB pawspos_offline)] end UI -.->|offline POS queue| IDB subgraph L2[L2 Edge] NX[Nginx TLS + proxy] end subgraph L3[L3 Application] EX[Express] MW[Middleware chain] TR[Tenant resolver + Auth] end subgraph L4[L4 Domain] RT[Route handlers] SV[Services] end subgraph L5[L5 Data] M[(Master DB)] T[(Tenant DB)] A[(Analytics DB)] end subgraph L6[L6 Integration] BR[Bridge WebSocket] DV[Devices / KDS / Printers] end UI --> NX NX --> EX EX --> MW MW --> TR TR --> RT RT --> SV SV --> M SV --> T SV --> A EX <--> BR BR <--> DV

Sequence: one HTTPS API call

sequenceDiagram participant Client as L1 Presentation participant Edge as L2 Nginx participant App as L3 Express+MW participant Domain as L4 Route+Service participant DB as L5 MySQL Client->>Edge: HTTPS /api/... Edge->>App: Proxy to Node App->>App: Session, tenant slug, auth App->>Domain: Handler Domain->>DB: Query tenant or master DB-->>Domain: Rows Domain-->>Client: JSON

Where to go next

Goal	Doc
Deep dive on request flow and barcode APIs	03 — Backend
Login, session, X-Tenant-Slug	05 — Auth & Tenancy
End-to-end traces (POS sale, signup)	Appendix: Data Flows
Digital signage (catalog, player, bridge)	26 — Signage & Displays
Every feature → route → chapter	25 — Platform Coverage
Platform ops (PM2, env, MySQL)	01, 02