TopoloCommerce

Authority

Service IDs:

Repos: PlatformApplications/TopoloCommerce

Hosts:

Dependencies: topolo-auth, applications-packages, topolo-mdm, topolo-nexus, topolo-device-platform, topolo-pay, topolo-venue-survey

Depends on Topolo Auth: yes

Contract Source

Type: curated

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

Source exists: 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.

API key scopes in Auth catalog: 19

Auth Requirements

No global OpenAPI security scheme is declared.

• 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

Runtime and Deployment

Wrangler surfaces: 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

Environment variables: CORS_ORIGINS, ENVIRONMENT, GUEST_WEB_ORIGIN, MDM_API_URL, NEXUS_GATEWAY_URL, NEXUS_VOICE_FALLBACK_MODEL, NEXUS_VOICE_FALLBACK_PROVIDER, NEXUS_VOICE_FINAL_FALLBACK_MODEL, NEXUS_VOICE_FINAL_FALLBACK_PROVIDER, NEXUS_VOICE_MODEL, NEXUS_VOICE_PROVIDER, NEXUS_VOICE_TRANSCRIPTION_MODEL, QURO_API_URL, QURO_REDIRECT_ORIGIN, TOPOLO_AUTH_URL

Routes: workers.dev or Pages-only delivery

Observability enabled: yes