TopoloCommerce

Documentation Map

• Application hub
• Application API surface
• Machine system JSON
• Machine application JSON
• applications/commerce

What It Is

Multi-vertical commerce workspace spanning a Worker API with extracted organization, queue, and team route modules, an authenticated org-scoped ops web app with canonical /venues/:venueId routes, a separate tablet-first station web app for kitchen, POS, bar, and expo execution against the same live queue contract with direct ticket detail and assignment controls plus phone-friendly lane switching, first-venue onboarding for confirmed empty orgs with strict org-context response handling, a stronger queue command-center shell with filterable live lanes, an inspection rail, and live draft-order visibility for back-of-house screens, staffing-aware queue and team workspaces with ready-now and coverage-gap views, a dedicated ops Experience Studio for venue guest branding, browse-mode control, currency and locale editing with live price preview, per-venue order-intent timer policy, and shared-tab opening requirements, merchandising-grade catalog and import review workspaces, item availability, compare-at pricing, bundle metadata, and modifier-group pricing in the live catalog contract, a live public guest runtime without hidden demo-org fallback, venue-configurable guest-web modes (`classic_menu`, `story_menu`, `reel_menu`) with immersive full-screen story and reel viewers that keep basket access and ordering inside the special view, a stable story shell with swipe-down dismiss, TikTok-style vertical reel navigation, a floating bottom-right voice launcher that now opens a compact guest voice drawer without interrupting browsing, uses server-side Cloudflare Whisper transcription plus a low-cost Cloudflare parser before escalating to `gpt-5.4-mini`, returns guest-facing response copy in the request language by default, supports on-demand translation backed by a reusable D1 translation cache, enforces guest approval before commit, mirrors live guest draft orders through the venue queue Durable Object so staff can see in-progress baskets before finalization, now opens QR-scoped table flows with explicit owner-created shared tabs plus owner-approved joins and optional tab-owner photo references instead of silent shared sessions, keeps the active shared tab and canonical order history stable across refresh on the same device, reconciles guest bill sessions against the current unpaid order scope so later orders do not reset prior payments, and can escalate to staff review with transcript plus optional recording playback, plus direct-entry venue pages that do not expose an in-app back path by default, active-venue-only guest writes, stricter team and ticket assignment validation, optimistic queue concurrency guards, a managed mobile guest surface, a local Venue Edge runtime with `edge_preferred`, `cloud_preferred`, and `cloud_only` modes, local sync-policy control, rescue-uplink runtime reporting, ticket-assignment notification delivery and acceptance support, local team section, team member, staff identity-method, venue device, device-session, and payment-reconciliation administration support on the edge, editable live venue catalogs, a Durable Object-backed live venue queue with stale-snapshot rejection, D1-backed replay-safe mutation and venue-event journals, canonical cloud device, identity, payment, sync-policy, and staff-notification ledgers, a per-venue queue revision ledger, cloud-side Venue Edge sync receipts plus event ingestion, cached-local resilience foundations, and a single richer shared suite demo org under topolo-demo-suite.

TopoloCommerce is the multi-vertical commerce workspace for the Topolo platform.

Current v1 surfaces:

This scaffold follows the canonical docs in `PlatformApplications/TopoloDocs`.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloDocs/src/content/public/applications/commerce.mdx

Source exists in repo: yes

Canonical public and internal docs cover the Topolo org to venue hierarchy, and the Commerce ops plus first-venue onboarding surfaces render through `TopoloAppShell`, inheriting shared Improve Topolo and TopoloNotify chrome while keeping venue operations Commerce-owned, authenticated org-scoped staff routing, canonical /venues/:venueId ops URLs, the separate `station-web` tablet execution surface for kitchen, POS, bar, and expo, first-venue onboarding for confirmed empty organizations plus explicit unavailable-state handling for malformed or non-JSON org-context responses, the stronger ops shell and queue command-center presentation, section-coverage and staffing-readiness context in the queue workspace, the filterable live-lane plus inspection-rail flow, member-workload visibility and ready-now or coverage-gap views in the team workspace, the extracted organization, queue, and team route modules, the richer catalog merchandising and import-provenance workspaces, the dedicated venue Experience Studio, the venue.config_json guest-experience contract, venue-level currency, locale, shared-tab opening requirement, and live price preview editing inside Experience Studio, live guest venue discovery from active venue rows instead of a hidden demo org, active-venue-only guest writes, replay-safe guest-session plus commerce-write recovery, stricter rejection of unknown team-section and staff-assignment ids, optimistic queue concurrency tokens on ticket updates, reserved guest-host redirects for platform-style paths such as `/dashboard`, direct-entry venue pages without an in-app back path by default, the split guest-web page or component structure and stronger editorial runtime presentation, venue-configurable guest browse modes (`classic_menu`, `story_menu`, `reel_menu`) with immersive full-screen story and reel viewers that keep basket access and add/customize actions inside the special view, behave like a short-lived draft session until final review, mirror those in-progress baskets into the venue queue Durable Object through `/api/draft-orders` so back-of-house screens can see incoming order intent before `/api/orders` finalization, keep those draft previews visible until the guest explicitly clears or finalizes the basket, expose per-venue `orderIntentTimer` settings so the guest runtime can show a visible countdown plus extend action before draft reset, expose per-venue `tableTabs.openingRequirement` so venues can keep name-only tab creation or require a one-time tab-owner photo reference with best-effort asset cleanup on owner close, replace silent QR-scoped guest-session minting with explicit owner-created shared table tabs plus owner-approved joins, persist shared tab membership in D1, hydrate shared guest order history through `/api/guest/tab`, validate active membership on guest writes and bill actions, restore the active shared tab plus cached order or bill state across refresh for the same device and table context, reconcile guest bill and tab views against the current unpaid order scope so later orders preserve the already-paid portion of the visit instead of resetting the whole bill, use the latest settled-bill cutoff to keep historically paid orders visibly marked as `Paid` in the guest tab while leaving the current unpaid scope as `Sent` or `Queued`, and offer `Keep tab open` or `Close tab` after full payment so the guest can explicitly reset the scoped session and start fresh, support a local `Maybe` list inside that draft session, support current-item removal from immersive views, keep compact review state in the immersive header, use balanced equal-size split add/remove actions in story mode, isolate the story action panel so taps on controls do not trigger story navigation, support visible in-story action feedback, automatic progression, hold-to-pause behavior, swipe-down dismiss, and a stable story shell that does not jump when items change, layer story copy and ordering controls over the portrait media instead of detached below it, allow compare-at pricing and bundle metadata on live catalog items for guest merchandising without changing the order hot path, use TikTok-style vertical swipe/scroll snap navigation in reel mode, a right-side vertical position rail instead of visible reel back/forward buttons or bottom pagination, expose voice from a floating launcher in the bottom-right of the guest runtime so it remains reachable from ordinary browsing plus immersive story or reel views, open that voice path as a compact drawer with one oversized circular listen/stop control and staged chat-style feedback, keep the drawer quiet until real speech or typed content exists, pause story auto-progression while the voice drawer is open, require explicit guest approval before matched items or requests are committed, route `/api/voice/resolve` through a tiered Nexus AI pipeline that prefers Cloudflare transcription with `@cf/openai/whisper-large-v3-turbo`, runs a low-cost Cloudflare structured parser with `@cf/meta/llama-3.1-8b-instruct-fast`, escalates to `openai/gpt-5.4-mini` only for ambiguous or higher-risk requests, reaches Nexus through the Commerce worker service binding in production, returns transcript language plus response language so guest-facing response copy can default to the request language, supports `/api/voice/translate` plus the D1 `voice_text_translations` cache for reusable translations instead of regenerating identical strings, returns summary, confidence, quantity-aware item matches, optional modifier hints, and optional linked service-request detail, keeps `xai/grok-4.20-beta-latest-non-reasoning` plus the heuristic matcher as downstream safety nets, supports escalation to staff review with transcript plus optional recording playback, includes `/api/voice/review-assets` for stored playback retrieval, plus module resolution contract, guest/runtime boundaries, editable venue catalog management, item availability and modifier-group pricing in the live catalog plus order contract, live queue streaming, team-management flows, cloud device-state reads, cloud staff-identity-method reads and writes, cloud payment-reconciliation reads and writes, cloud sync-policy reads and writes, cloud staff-notification reads and acceptance writes, cached-local resilience behavior, the module-aware resilience surface, replay-safe browser outbox recovery, the D1-backed `venue_queue_revisions` ordering ledger, Durable Object stale-snapshot rejection, cloud-side venue event journaling, the local Venue Edge runtime, the current edge-side team section, team member, staff identity-method, venue device, device-session, payment-reconciliation, sync-policy, and staff-notification administration flows, the cloud-side Venue Edge enrollment plus bootstrap or journal-sync contract, the new `/api/venues/:venueId/edge/push` ingestion path, per-event sync receipts in `commerce_edge_sync_receipts`, canonical cloud ledgers in `venue_devices`, `venue_device_sessions`, `venue_staff_identity_methods`, `venue_payment_reconciliations`, `venue_sync_policies`, and `venue_staff_notifications`, support for `edge_preferred`, `cloud_preferred`, or `cloud_only` hot-path selection, local rescue-uplink runtime reporting through edge-node metadata, branded ops and station login routes that use the synchronized auth client without an initial unauthenticated refresh probe, the consolidation of Commerce demo data under topolo-demo-suite, the richer shared demo dataset carried by that org, the native authenticated `GET /api/widget` live-workspace endpoint served from the Commerce API worker, and the shared platform integrations with Auth, MDM, Nexus, Topolo Device Platform, Pay, and Venue Survey, with station-web now consuming the Durable Object live-stream route for immediate cross-screen ticket updates while retaining polling fallback, direct ticket detail plus assignment controls, and a compact lane-selector plus bottom-sheet flow on phone-sized screens.

App API page: /reference/apps/topolo-commerce

This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.

Auth and Permissions

Depends on Topolo Auth: yes

Service IDs:

API key scopes

Service permissions

catalog:read, catalog:write, dashboard:read, devices:read, devices:write, imports:read, imports:write, payments:create, publishing:read, publishing:write, queues:read, queues:write, reports:read, service_requests:read, service_requests:write, settings:read, settings:write, venues:read, venues:write

Data Ownership

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: yes

Wrangler surfaces

• PlatformApplications/TopoloCommerce/apps/api/wrangler.toml -> topolo-commerce-api
• PlatformApplications/TopoloCommerce/apps/guest-web/wrangler.toml -> topolo-commerce-guest-web
• PlatformApplications/TopoloCommerce/apps/ops-web/wrangler.toml -> topolo-commerce-ops-web
• PlatformApplications/TopoloCommerce/apps/station-web/wrangler.toml -> topolo-commerce-station-web

Build and deploy commands

• build — PlatformApplications/TopoloCommerce/apps/api/package.json :: node --check src/index.js
• predeploy — PlatformApplications/TopoloCommerce/apps/api/package.json :: node ./scripts/check-migrations.mjs
• deploy — PlatformApplications/TopoloCommerce/apps/api/package.json :: wrangler deploy
• build — PlatformApplications/TopoloCommerce/apps/guest-web/package.json :: vite build
• preview — PlatformApplications/TopoloCommerce/apps/guest-web/package.json :: vite preview
• deploy — PlatformApplications/TopoloCommerce/apps/guest-web/package.json :: npm run build && CLOUDFLARE_ACCOUNT_ID=49ef1ba682ad8cfd720c86699ae17521 wrangler pages deploy dist --project-name topolo-commerce-guest-web
• build — PlatformApplications/TopoloCommerce/apps/ops-web/package.json :: vite build
• preview — PlatformApplications/TopoloCommerce/apps/ops-web/package.json :: vite preview
• deploy — PlatformApplications/TopoloCommerce/apps/ops-web/package.json :: npm run build && CLOUDFLARE_ACCOUNT_ID=49ef1ba682ad8cfd720c86699ae17521 wrangler pages deploy dist --project-name topolo-commerce-ops-web
• build — PlatformApplications/TopoloCommerce/apps/station-web/package.json :: vite build
• preview — PlatformApplications/TopoloCommerce/apps/station-web/package.json :: vite preview
• deploy — PlatformApplications/TopoloCommerce/apps/station-web/package.json :: npm run build && CLOUDFLARE_ACCOUNT_ID=49ef1ba682ad8cfd720c86699ae17521 wrangler pages deploy dist --project-name topolo-commerce-station-web
• build — PlatformApplications/TopoloCommerce/apps/venue-edge/package.json :: node --check src/index.js && node --check src/server.js

Failure Modes

No default failure-mode heuristics are currently flagged for this system.

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloCommerce/apps/api/wrangler.toml
• PlatformApplications/TopoloCommerce/apps/guest-web/wrangler.toml
• PlatformApplications/TopoloCommerce/apps/ops-web/wrangler.toml
• PlatformApplications/TopoloCommerce/apps/station-web/wrangler.toml
• PlatformApplications/TopoloDocs/src/content/public/applications/commerce.mdx
• PlatformApplications/TopoloCommerce/README.md
• PlatformApplications/TopoloCommerce/apps/api/package.json
• PlatformApplications/TopoloCommerce/apps/guest-web/package.json
• PlatformApplications/TopoloCommerce/apps/ops-web/package.json
• PlatformApplications/TopoloCommerce/apps/station-web/package.json
• PlatformApplications/TopoloCommerce/apps/venue-edge/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-27

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.