internal active Last verified 2026-04-10

TopoloCommerce Handbook

Internal handbook for the multi-vertical commerce workspace, its org-to-venue hierarchy, module resolution model, and the boundary between guest, staff, and platform-owned integrations.

Owners
commerce
Source Repos
PlatformApplications/TopoloCommerce
Systems
Topolo Auth, TopoloCommerce, Topolo Nexus, TopoloMDM, Topolo Nodo, Topolo Pay, Topolo Venue Survey
Tags
commerce, venues, modules, kiosk

What It Is

TopoloCommerce is the multi-vertical commerce application for Topolo orgs that operate one or many venues.

It is explicitly not hospitality-only. The base platform model is:

  • one Topolo org
  • many venues under that org
  • shared commerce core
  • optional vertical packs enabled per venue

V1 ships four coordinated surfaces:

  • apps/api as the Worker API and domain owner
  • apps/ops-web as the signed-in Topolo suite app for staff and chain operations
  • apps/guest-web as the public venue guest runtime
  • apps/guest-mobile as the managed Flutter kiosk runtime

Architecture

PlatformApplications/TopoloCommerce follows a workspace cluster layout similar to other modern multi-surface Topolo apps.

Core boundaries:

  • apps/api owns org settings, venue settings, module resolution, catalog state, guest sessions, carts, orders, service requests, bookings, tickets, device-assignment metadata, publish metadata, and venue payment-mode configuration
  • apps/ops-web is the only first-party signed-in launcher surface in v1
  • apps/guest-web and apps/guest-mobile are venue-scoped customer runtimes and do not expose the Topolo launcher in ordinary guest flow
  • packages/shared owns the canonical module collections, presets, helper functions, and shared sample data used by the initial surfaces

The canonical tenancy model is organization -> venues. Every venue-scoped record must carry both org_id and venue_id.

The module contract mirrors the CRM-style module-settings model:

  • commerce_org_settings stores org defaults and preset selection
  • commerce_venue_settings stores venue overrides
  • effective module visibility is org defaults + preset + venue overrides + dependency resolution
  • route visibility in the ops and guest surfaces must follow effective module state rather than hardcoded vertical assumptions

Runtime Surfaces

apps/api

  • health route at /health
  • org context and module-resolution routes
  • public guest venue discovery routes
  • venue detail, catalog, queue, guest-session, order, service-request, booking, voice-resolution, payment-session, and team-management routes
  • live D1-backed queue transitions and import approvals
  • Durable Object-backed venue queue snapshots and live stream fanout for ops updates

apps/ops-web

  • public landing and login entry
  • Topolo Auth callback handling
  • signed-in shell with Topolo launcher, shared bug reporter, venue switcher, and module-aware route visibility
  • canonical venue-scoped ops URLs now use /venues/:venueId/... instead of a query-string venue selector
  • cached org and venue snapshots plus a local outbox for queued staff actions during cloud interruption, all scoped per authenticated org instead of shared browser-global keys
  • live queue board with ticket transitions, section assignment, and staff assignment
  • resilience route showing the venue event journal, replay-safe mutation posture, current queue projection mode, and cloud-side Venue Edge enrollment plus sync posture
  • import approval lane
  • team management lane for sections, roster resources, and wearable/device-linked notification ownership
  • catalog, hospitality, retail, and service views backed by the live Commerce API, with the catalog route now supporting real section, item, and service-action editing

apps/guest-web

  • public venue picker
  • public guest venue discovery resolves from live active venue rows instead of a hidden default demo org
  • venue-aware guest runtime that adapts to hospitality, retail, service, or hybrid venues
  • cached venue snapshots, basket persistence, and a local outbox for guest orders, service requests, and bookings during cloud interruption
  • guest runtime and venue discovery must not silently fall back to seeded demo venues in normal deployments; only explicit local demo mode may use sample data
  • live guest session creation
  • order, service-request, and booking submission
  • optional voice-assist panel with transcript confirmation and intent resolution without requiring voice for completion

apps/guest-mobile

  • managed-device-first Flutter shell
  • venue-aware kiosk runtime contract
  • topolo_auth_flutter reserved for operator setup, diagnostics, or recovery rather than ordinary guest flow

API Reference

The initial route families are implemented in:

  • PlatformApplications/TopoloCommerce/apps/api/src/index.js
  • PlatformApplications/TopoloCommerce/apps/api/src/auth.js
  • PlatformApplications/TopoloCommerce/packages/shared/src/modules.js

Current route families:

  • /health
  • /api/guest/venues
  • /api/guest/venues/:venueSlug
  • /api/org/context
  • /api/org/module-settings
  • /api/org/module-settings with PUT for stored org defaults
  • /api/org/module-settings/resolve
  • /api/venues
  • /api/venues/:venueId
  • /api/venues/:venueId with PUT for venue preset and module override updates
  • /api/venues/:venueId/catalog
  • /api/venues/:venueId/catalog with PUT for catalog saves from ops-web
  • /api/venues/:venueId/resilience/state
  • /api/venues/:venueId/edge/nodes
  • /api/venues/:venueId/edge/bootstrap
  • /api/venues/:venueId/edge/events
  • /api/venues/:venueId/edge/ack
  • /api/venues/:venueId/imports
  • /api/venues/:venueId/imports/:importId/approve
  • /api/venues/:venueId/ops/tickets
  • /api/venues/:venueId/ops/live-state
  • /api/venues/:venueId/ops/live-stream
  • /api/venues/:venueId/ops/tickets/:ticketId
  • /api/venues/:venueId/team
  • /api/venues/:venueId/team/sections
  • /api/venues/:venueId/team/members
  • /api/venues/:venueId/team/members/:memberId
  • /api/guest/sessions
  • /api/orders
  • /api/service-requests
  • /api/bookings
  • /api/voice/resolve
  • /api/payment-sessions

The API contract now persists org, venue, catalog, queue, import-review, order, service-request, booking, venue-section, and staff-roster state in production D1. Public guest venue discovery must read live active venue rows instead of anchoring itself to a seeded demo org, while explicit local demo mode may still use sample fixtures outside the production runtime. The route shape now supports a real guest-to-ops loop: guests can open sessions, submit orders or requests, create bookings, and have that work land in the live venue queue where staff can transition and assign ticket state directly from ops-web. The venue queue snapshot is coordinated through VENUE_QUEUE_COORDINATOR, which allows the signed-in ops app to receive live venue updates without waiting on manual refresh.

The current write contract is replay-safe for the browser outbox foundation:

  • guest and ops write routes accept an optional clientMutationId in the request body
  • D1 stores successful replay-safe mutation results in commerce_mutation_journal
  • D1 stores venue activity in the append-only commerce_venue_event_journal
  • D1 stores enrolled Venue Edge nodes and their bootstrap, sync, last-seen, and acknowledged-cursor state in commerce_venue_edge_nodes
  • replaying the same route with the same clientMutationId returns the original successful response instead of creating a duplicate order, request, booking, ticket transition, section, or team-member change
  • Durable Object fanout remains a derived live-queue layer, so persisted D1 writes should still succeed even if the queue cache cannot be refreshed immediately
  • the current Venue Edge contract is still cloud-side only: operators can enroll a node, the node can bootstrap a venue snapshot, page the event journal after a cursor, and acknowledge the latest synced cursor back to Commerce

Auth and Permissions

apps/ops-web uses the shared browser auth contract:

  • @topolo/auth-client
  • @topolo/ui-kit
  • Auth-managed login_config metadata with authenticated_home_path = /dashboard

apps/api uses @topolo/auth-middleware for staff and admin routes. The thin app-local wrapper forwards:

  • serviceId = srv_topolo_commerce
  • TOPOLO_AUTH_URL
  • optional local JWT secret
  • optional service API key for Auth introspection

Guest surfaces do not require ordinary human Topolo Auth in normal use. Their runtime identity should stay venue-scoped or device-scoped.

Permission and API-key scope seeds now exist for TopoloCommerce in PlatformApplications/TopoloAuth/scripts/seed-service-permissions.sql and PlatformApplications/TopoloAuth/scripts/seed-service-api-key-scopes.sql. TopoloCommerce also requires checked-in role bundles for staff-facing access. The canonical seed sources are PlatformApplications/TopoloAuth/scripts/seed-role-bundles.sql and PlatformApplications/TopoloAuth/scripts/add-topolo-commerce-service-production.sql, including the privileged staff roles super_admin, platform_admin, owner, admin, and tenant_admin.

Staff routes must resolve the organization from the authenticated Topolo Auth session. They must not fall back to the demo org when the authenticated org differs or when Commerce has no seeded data for that org yet. If Commerce has no org row for the authenticated org, the API should return an empty org-scoped workspace rather than leaking demo venues.

Normal runtime surfaces must also avoid seeded UI fallback. Outside explicit local demo mode, the signed-in ops app and guest runtime should use only live Commerce data or cached snapshots previously obtained for that exact org or venue.

Data Ownership

TopoloCommerce owns:

  • org defaults and venue overrides for module state
  • venue records and venue-local configuration
  • catalog and menu assignments
  • import jobs and publish revisions
  • guest sessions
  • carts and orders
  • service requests and bookings
  • queue tickets and staff-lane state
  • venue team sections, roster resources, and assignment traceability
  • venue resilience state and the cloud-side venue event journal
  • venue edge-node enrollment state and the cloud-side bootstrap or sync cursor contract
  • venue device-assignment intent
  • venue-specific DOOH publish artifacts
  • venue payment-mode configuration

Other systems remain authoritative for their own domains:

  • Topolo Auth owns identity, service registration, and launcher metadata
  • Topolo Pay owns transaction execution and settlement state
  • Topolo Nexus owns AI provider invocation and typed transcription infrastructure
  • Topolo MDM owns managed-device execution
  • Nodo owns feed and display runtime execution
  • Topolo Venue Survey remains the intake pattern for venue onboarding assets

Deployments

The canonical deployment metadata lives in PlatformApplications/TopoloCommerce/topolo.cloudcontrol.json.

Current production surfaces:

  • Worker API: https://topolo-commerce-api.topolo.workers.dev
  • Ops web: https://commerce.topolo.app
  • Guest web: https://guest.topolo.app

Production runtime bindings:

  • D1: topolo-commerce-prod-db-primary
  • R2: topolo-commerce-prod-r2-assets
  • Durable Object: VENUE_QUEUE_COORDINATOR

The root repo carries .github/workflows/ci.yml, and the Topolo Auth production catalog now points srv_topolo_commerce at the live ops URL so launcher and sign-in metadata resolve to the deployed surface.

The legacy pages.dev hosts remain deploy targets, but the browser entrypoints should redirect to the custom domains so Auth CORS and shared launcher flows resolve against the canonical Topolo hosts.

Failure Modes

  • venue route visibility drifts from effective module settings and reintroduces hardcoded vertical assumptions
  • guest surfaces accidentally inherit Topolo launcher or signed-in staff shell behavior
  • staff routes drift away from @topolo/auth-middleware and reintroduce app-local auth verification
  • venue-level payment mode is conflated with Topolo Pay transaction ownership
  • MDM device-role intent and actual managed-device execution responsibilities become blurred
  • DOOH publishing starts behaving like a parallel rendering runtime instead of a Nodo feed artifact producer
  • browser-local replay paths stop sending stable clientMutationId values and duplicate guest or staff writes during recovery

Debugging

  • start with PlatformApplications/TopoloCommerce/packages/shared/src/modules.js when route or UI visibility looks wrong
  • inspect apps/api/src/index.js for the current route families and auth boundaries
  • inspect apps/api/src/index.js plus commerce_venue_event_journal when resilience state or venue event history looks wrong
  • inspect apps/api/src/index.js plus commerce_venue_edge_nodes when an enrolled Venue Edge node is not bootstrapping, syncing, or advancing its acknowledged cursor
  • inspect apps/api/src/venueQueueCoordinator.js when guest-created work is not appearing in ops in real time
  • inspect apps/api/src/auth.js first when a signed-in operator is getting 403 on /api/org/context or /api/venues/:venueId
  • inspect apps/ops-web/src/App.jsx for module-aware navigation and venue switching
  • inspect apps/ops-web/src/App.jsx and apps/ops-web/src/styles/app.css when staffing, assignment, or realtime lane behavior drifts
  • inspect apps/guest-web/src/App.jsx when a guest venue runtime is rendering the wrong vertical flow
  • inspect /internal/apps/commerce-resilience before changing cached-local or offline behavior
  • verify srv_topolo_commerce exists in Auth seed files, and confirm its service_role_permissions rows include the live operator role before treating a 403 as an app-shell bug
  • confirm TopoloCommerce is present in PlatformApplications/packages/topolo-ui-kit/src/firstPartyApps.ts when shared launcher or iconography is missing

Change Log / Verification

  • Updated internal coverage on 2026-04-10 to document authenticated org-scoped staff routing, the removal of demo-org fallback for staff APIs, and canonical /venues/:venueId/... ops URLs

  • Updated internal coverage on 2026-04-10 to document that public guest venue discovery now resolves from live active venues instead of a hidden demo-org fallback

  • Updated internal coverage on 2026-04-10 to document that demo data is only valid in explicit local demo mode and must not silently backfill normal guest or ops runtime paths

  • Added the canonical TopoloCommerce system coverage, workspace contract, and org-to-venue module model on 2026-04-10

  • Verified that the initial repo scaffold now includes the Worker API, signed-in ops surface, public guest web runtime, managed guest mobile scaffold, and CloudControl metadata on 2026-04-10

  • Corrected staff-route authorization and denied-state handling on 2026-04-10 so privileged operator roles now map cleanly through Auth and ops-web no longer renders seeded venue fallback under a real 403

  • Verified on 2026-04-10 that guest-web now creates live guest sessions and can submit orders, service requests, and bookings into the D1-backed venue queue, while ops-web can transition live tickets and approve import jobs

  • Verified on 2026-04-10 that replayed guest and ops writes now use stable clientMutationId values plus commerce_mutation_journal in D1 so retrying queued actions does not create duplicate venue records

  • Verified on 2026-04-10 that Commerce now records a cloud-side append-only venue event journal and exposes a module-aware resilience surface in ops-web

  • Verified on 2026-04-10 that Commerce now exposes the first cloud-side Venue Edge control-plane contract for node enrollment, bootstrap snapshots, journal pull, and cursor acknowledgement without yet claiming a full local venue authority

  • Verified on 2026-04-10 that the ops Catalog route is no longer read-only and now persists catalog name, service actions, sections, and items back into the live Commerce catalog definition

  • Extended the live queue model on 2026-04-10 with a Durable Object-backed venue queue stream, seeded team-management tables, and ops-web staffing surfaces so guest-created work appears in the venue lane without refresh and can be assigned to sections or staff resources

  • Added the phase-1 resilience foundation on 2026-04-10 so guest-web and ops-web now keep cached snapshots and replay queued local actions after temporary cloud interruption