TopoloCommerce | Topolo Docs

What It Is

TopoloCommerce is the multi-vertical commerce platform for teams that need one operating system across many venues.

It supports:

one Topolo org with many venues
shared commerce foundations
venue-level module packs for hospitality, retail, or service workflows
guest-facing and staff-facing runtime surfaces in the same platform model

Architecture

TopoloCommerce is organized as a multi-surface workspace:

Worker API
signed-in operations app
signed-in tablet-first station app
public guest web runtime
managed mobile guest runtime
local Venue Edge runtime

The platform resolves effective venue behavior from org defaults, venue overrides, and preset-based module packs instead of hardcoding one vertical operating model.

Runtime Surfaces

See /systems/topolo-commerce for the current runtime inventory.

The main public-facing understanding is:

staff and chain operators use the signed-in ops app plus a separate tablet-first station app for kitchen, POS, bar, and expo execution
authenticated orgs without any venues now enter a first-venue onboarding flow instead of an empty dead end
the signed-in ops app now uses canonical venue-scoped URLs in the form /venues/:venueId/...
the signed-in ops app now presents venue context and queue state more like a live command center than a generic admin dashboard
the signed-in ops app now surfaces section coverage, staffing readiness, and member workload inside the live queue and team workspaces
the signed-in ops app now includes filterable live lanes with a ticket inspection rail plus ready-now and coverage-gap staffing views
the signed-in ops app now includes a venue Experience Studio so operators can set guest browse mode, palette, typography, logo, quick-action treatment, guest draft-timer policy, and shared tab opening requirement per venue
guests use venue-scoped web or managed-device surfaces that can now submit live orders, service requests, and bookings
guest writes now target only active venues, so unpublished venues cannot keep receiving sessions or orders through stale client state
the public guest host reserves platform-style paths such as /dashboard, /login, /callback, and /auth/* and redirects them to the guest landing instead of treating them as venue slugs
the public guest-web runtime now uses a stronger editorial landing, vertical-specific venue presentation, venue-configurable guest modes (classic_menu, story_menu, reel_menu), and a touch-first basket layout instead of a generic venue grid plus flat catalog view
direct venue pages now assume QR or table-link entry and therefore do not expose an in-app back path to the venue picker by default
story_menu and reel_menu now keep browsing and ordering inside immersive full-screen viewers instead of relying only on flat inline cards
guest ordering now behaves like a short-lived draft session, so nothing is sent until the guest reviews and places the full order, while the in-progress basket is mirrored through the venue queue Durable Object so back-of-house staff can see incoming intent before final submission, guests see a venue-configurable countdown before draft reset with an extend option near expiry, table QR flows now open with an explicit Create new tab or owner-approved Join tab choice instead of silently minting a new shared session, venues can optionally require a tab-owner photo reference before a new shared tab opens, refresh restores the current table tab on the same device, and the guest bill or tab flow now keeps prior payments visible when new orders are added instead of resetting the whole visit as unpaid
immersive story and reel views now expose direct basket access, current-item removal, a local Maybe path inside the short-lived draft session, and in-view add/customize actions, with story_menu supporting swipe navigation, swipe-down dismiss, compact review state in the header, an isolated equal-size split action row, visible action feedback, automatic progression with hold-to-pause behavior, a static Instagram-style story shell, and copy or ordering controls layered over the portrait media, plus compare-at price and bundle merchandising where configured, and reel_menu using TikTok-style vertical swipe/scroll snap navigation between section items plus a right-side vertical position rail
immersive story and reel views now also use reduced-motion-safe transition choreography rather than abrupt item swaps
voice capture now sits behind a floating circular launcher in the guest runtime, opens into a compact drawer with one oversized listen/stop control so guests can keep browsing while they speak, stays quiet until real speech or typed content exists, then responds through a chat-style voice feed with confirmations and direct basket review actions, prefers server-side transcription of the captured recording through Nexus when available, treats that captured audio as the authoritative transcript source instead of biasing it with the browser draft transcript, uses a low-cost Cloudflare first-pass parser, escalates to gpt-5.4-mini only for ambiguous or higher-risk requests, returns guest-facing response copy in the request language by default, supports on-demand translation backed by a reusable D1 translation cache, and can still escalate to staff review with transcript plus optional recording playback when browser capture is available
venue teams can manage sections, assign staff resources, and work live queue items as they arrive
venue teams can also open station-commerce.topolo.app for a live staff-station surface, where Point of Sale now follows checkout_support tickets, Bar Board projects beverage and pickup-adjacent work from the shared queue, Expo Window combines kitchen, dispatch, and handoff-ready pickup work on a tablet-first board, ticket movement appears across station tablets immediately through the Commerce live queue stream, and staff can open richer ticket details plus update ticket assignment directly from the station UI
the station surfaces now adapt more intentionally across screen sizes, keeping the multi-lane board on larger displays while switching to a compact lane-selector plus bottom-sheet ticket detail flow on phone-sized screens
venue operators can now edit the live venue catalog from ops in a stronger merchandising workspace instead of only viewing seeded catalog content
venue operators can now review imports with visible source provenance, vertical context, timestamps, and operator notes before approving draft content
guest and ops surfaces now keep cached local state and replay queued actions after temporary cloud interruption
the local Venue Edge runtime can now run in edge_preferred or cloud_preferred mode so venues can keep edge as the normal hot path or keep cloud as the hot path when required
the local Venue Edge runtime now syncs all currently supported edge-authored operational records into Commerce cloud for visibility instead of only syncing a journal subset, including current team administration, venue device registration, shared-terminal identity methods, device-session attribution, and payment-reconciliation markers
the local Venue Edge runtime now also syncs venue sync-policy changes plus staff notification and notification-acceptance state, and it reports current rescue-uplink activation posture back into Commerce cloud when connectivity is available
replay-safe guest writes now cover guest sessions as well as orders, service requests, and bookings
live queue reads now fall back cleanly to D1 if the Durable Object snapshot cache is unavailable
signed-in venue workspaces are scoped to the authenticated Topolo org and no longer fall back to demo venues when a different org signs in
public guest venue discovery now resolves from live active venues instead of a hidden default demo org
normal guest and ops runtimes now use only live Commerce data or cached real snapshots; demo content is reserved for explicit local demo mode and is consolidated under topolo-demo-suite
the shared topolo-demo-suite demo org now carries a richer multi-vertical Commerce dataset instead of a Commerce-only duplicate demo org
replayed guest and ops writes now carry stable clientMutationId values so temporary connectivity loss does not create duplicate venue records during recovery
venue operators can now inspect a dedicated resilience view showing the current cloud journal, recovery posture, and enrolled Venue Edge nodes for a venue
venue boards and DOOH outputs publish through the existing Nodo runtime

API Reference

The current route families cover org context, module resolution, venue list and creation, venue detail, venue experience reads and saves, catalog reads and saves, venue resilience state, venue sync-policy reads and writes, Venue Edge node enrollment and sync, guest venue discovery, guest-session creation, explicit table-tab creation or join approval for QR-scoped tables, live draft-order sync, live order and request submission, voice-intent resolution, voice response translation, queue reads and transitions, live queue streaming, team management, staff-identity-method reads and writes, device-state reads, staff-notification reads and acceptance writes, payment-reconciliation reads and writes, import approvals, and payment-session creation. Public guest writes accept only active venues, staff assignment writes reject invalid section or staff ids instead of clearing them implicitly, and queue ticket writes can reject stale optimistic-concurrency tokens when an operator acts on an out-of-date ticket copy. The venue experience contract now also includes per-venue orderIntentTimer settings that drive the guest-visible countdown and extend window plus tableTabs.openingRequirement, where none keeps name-only tab creation and photo_reference requires a one-time tab-owner reference image before the API opens a new shared tab, then removes the stored object on a best-effort basis when the owner closes that tab. The live draft-order contract mirrors in-progress guest baskets through the same venue queue Durable Object that powers back-of-house live state, those drafts remain visible until the guest explicitly clears or submits the basket, table-scoped guest flows now use owner-created shared tabs with explicit join approval plus per-member access checks on guest writes, refresh restores the active shared tab on the same device, and the finalized order route clears the matching draft preview once the guest commits. Voice-intent resolution now prefers Nexus Cloudflare transcription with @cf/openai/whisper-large-v3-turbo, then a low-cost Cloudflare parser with @cf/meta/llama-3.1-8b-instruct-fast, and only escalates to openai/gpt-5.4-mini when the cheap pass is ambiguous or higher-risk, with Commerce calling Nexus through an internal service binding in production, returning guest-facing response copy in the request language, reusing cached text translations through D1, and retaining xAI plus heuristic safety nets behind that.

The current resilience contract also includes replay-safe guest and staff mutations for the browser outbox model plus the first full Venue Edge contract: bootstrap, journal pull, event push, cursor acknowledgement, and a local runtime that can operate with edge or cloud as the preferred hot path.

Use /systems/topolo-commerce plus the internal handbook for the current route inventory.

Auth and Permissions

The signed-in ops and station surfaces use shared Topolo Auth and the first-party suite launcher contract. Browser callback-code redemption runs through the synchronized @topolo/auth-client package and rejects direct token callback parameters. Branded first-party /login routes render without an initial unauthenticated Auth refresh probe; protected app boot still uses cookie refresh. Auth service metadata for srv_topolo_commerce must allow both https://commerce.topolo.app and https://station-commerce.topolo.app as browser callback origins. Protected staff API bearer tokens are validated through Auth /validate; Commerce does not keep a local JWT-secret trust path. Commerce also follows the canonical Auth role ladder. Platform-wide bypass belongs only to platform_super_admin and platform_admin users in the Auth admin org; org-scoped super_admin stays an org role and staff worker access still depends on explicit Commerce permissions.

Guest surfaces are venue-scoped runtimes and do not behave like ordinary signed-in Topolo suite apps.

Data Ownership

TopoloCommerce owns venue configuration, module settings, catalog and menu data, guest sessions, carts, orders, service requests, bookings, queue state, device-assignment intent, and venue-specific publish metadata.

Topolo Pay, Topolo Nexus, Topolo MDM, and Nodo continue to own their own execution domains.

Deployments

TopoloCommerce currently deploys to:

https://topolo-commerce-api.topolo.workers.dev
https://commerce.topolo.app
https://guest.topolo.app
https://station-commerce.topolo.app

CloudControl remains the source of truth for the current Worker, Pages, and storage bindings.

Failure Modes

venue behavior drifts from the shared module-resolution contract
guest and staff boundaries blur and the wrong runtime surface inherits the wrong auth or launcher behavior
venue team and assignment state drifts from the live queue model and breaks traceability
venues depend on cloud reachability because cached-local replay behavior is removed or bypassed
venues depend on replaying non-idempotent writes and create duplicates after short connectivity loss
venues lack visibility into their own recovery posture because resilience state is not surfaced in the signed-in workspace
venues cannot advance toward full local authority if edge enrollment and cursor sync drift from the canonical Commerce contract
venues can lose cross-venue visibility if edge-authored operational records stop syncing into cloud canonical state
platform integrations such as MDM, Pay, or Nodo are treated as local Commerce responsibilities instead of contract boundaries

Debugging

Start with /systems/topolo-commerce and the current internal handbook when checking route availability, venue behavior, or module-driven UI visibility.

Change Log / Verification

Updated public coverage on 2026-04-20 to document that Commerce ops and station branded login routes use the synchronized auth client without an initial unauthenticated refresh probe.
Updated public coverage on 2026-04-19 to document the station Commerce Auth callback origin required for station-commerce.topolo.app sign-in.
Updated public coverage on 2026-04-18 to document synchronized shared-auth callback handling for the signed-in ops and station surfaces.
Updated public coverage on 2026-04-16 to document venue-configurable shared-tab opening requirements, including optional tab-owner photo reference capture before a new tab opens
Updated public coverage on 2026-04-16 to document the new table-tab entry model for QR-scoped tables, where guests must create a new tab or request to join an active one, tab owners approve joins, guest writes are checked against active membership, and fully paid tabs can be explicitly closed back to the chooser instead of silently starting over
Updated public coverage on 2026-04-15 to document live draft-order previews between guest baskets and back-of-house queue screens through the venue queue Durable Object
Updated public coverage on 2026-04-15 to document the live station-web staff surfaces for kitchen, POS, bar, and expo execution
Updated public coverage on 2026-04-15 to document that station-web now consumes the Commerce live queue stream for immediate cross-screen ticket updates
Updated public coverage on 2026-04-15 to document direct ticket assignment plus phone-friendly responsive station flows in station-web
Updated public coverage on 2026-04-11 to document that the checked-in ops and guest browser runtimes no longer expose VITE_SKIP_AUTH preview branches and now use only live or cached Commerce data paths
Added canonical TopoloCommerce public coverage on 2026-04-10 for the new multi-vertical org-to-venue commerce platform
Updated public coverage on 2026-04-10 to include the live queue stream and team-management contract now present in production Commerce
Updated public coverage on 2026-04-10 to include the current cached-local resilience foundation for guest and ops surfaces
Updated public coverage on 2026-04-10 to include replay-safe guest and ops writes for the current cached-local resilience foundation
Updated public coverage on 2026-04-10 to include the signed-in venue resilience view and cloud-side venue event journal
Updated public coverage on 2026-04-10 to include Venue Edge node enrollment and the cloud-side bootstrap plus journal-sync contract
Updated public coverage on 2026-04-10 to include live catalog editing from the signed-in ops surface
Updated public coverage on 2026-04-10 to include authenticated org-scoped staff workspaces and canonical /venues/:venueId/... ops URLs
Updated public coverage on 2026-04-10 to clarify that demo content is not a normal runtime fallback outside explicit local demo mode
Updated public coverage on 2026-04-10 to clarify that public guest venue discovery reads live active venues instead of a hidden demo-org fallback
Updated public coverage on 2026-04-10 to clarify that Commerce demo content is consolidated under topolo-demo-suite
Updated public coverage on 2026-04-10 to clarify that the shared topolo-demo-suite org now holds the richer Commerce demo dataset in place of Commerce-only duplicate demo ownership
Updated public coverage on 2026-04-10 to reflect the current guest-web production pass structure and the stronger vertical-specific guest runtime presentation
Updated public coverage on 2026-04-10 to reflect the richer staffing-aware queue and team workspaces now present in the signed-in ops app
Updated public coverage on 2026-04-11 to document guest-host reserved path redirects for platform-style routes such as /dashboard
Updated public coverage on 2026-04-11 to document venue-configurable guest browse modes plus the new ops Experience Studio for guest branding and presentation control
Updated public coverage on 2026-04-11 to document the local Venue Edge runtime, its edge_preferred and cloud_preferred modes, the requirement that current edge-authored operational records sync back into Commerce cloud, and the current team, identity-method, and device/session administration support in that edge contract
Updated public coverage on 2026-04-11 to document edge-side payment reconciliation markers for external terminal, cash, house-account, and deferred settlement flows
Updated public coverage on 2026-04-12 to document venue sync-policy control, staff notification acceptance, and rescue-uplink runtime reporting in the current Venue Edge contract
Updated public coverage on 2026-04-12 to document that direct venue entry no longer exposes an in-app back path and that story_menu or reel_menu now keep basket access and ordering inside immersive full-screen viewers, with reel_menu using vertical snap navigation