application public active Verified 2026-04-10

TopoloCommerce

Multi-vertical commerce workspace spanning a Worker API, an authenticated org-scoped ops web app with canonical /venues/:venueId routes, a live public guest runtime without hidden demo-org fallback, a managed mobile guest surface, editable live venue catalogs, a Durable Object-backed live venue queue, D1-backed replay-safe mutation and venue-event journals, a cloud-side Venue Edge enrollment and sync contract, and cached-local resilience foundations.

Documentation Map

What It Is

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

Current v1 surfaces:

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

Architecture

Owners: commerce

Source repos: PlatformApplications/TopoloCommerce

Dependencies: topolo-auth, topolo-mdm, topolo-nexus, topolo-nodo, topolo-pay, topolo-venue-survey

Repo shape

PlatformApplications/TopoloCommerce/README.md
PlatformApplications/TopoloCommerce/apps/
PlatformApplications/TopoloCommerce/infra/
PlatformApplications/TopoloCommerce/package-lock.json
PlatformApplications/TopoloCommerce/package.json
PlatformApplications/TopoloCommerce/packages/
PlatformApplications/TopoloCommerce/topolo.cloudcontrol.json

Runtime Surfaces

Hosts:

https://commerce.topolo.app

topolo-commerce-api

Config: PlatformApplications/TopoloCommerce/apps/api/wrangler.toml

Main: src/index.js

Routes: workers.dev or asset-only surface

topolo-commerce-guest-web

Config: PlatformApplications/TopoloCommerce/apps/guest-web/wrangler.toml

Main: not declared

Routes: workers.dev or asset-only surface

topolo-commerce-ops-web

Config: PlatformApplications/TopoloCommerce/apps/ops-web/wrangler.toml

Main: not declared

Routes: workers.dev or asset-only surface

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, authenticated org-scoped staff routing, canonical /venues/:venueId ops URLs, live guest venue discovery from active venue rows instead of a hidden demo org, module resolution contract, guest/runtime boundaries, editable venue catalog management, live queue streaming, team-management flows, cached-local resilience behavior, the module-aware resilience surface, replay-safe browser outbox recovery, cloud-side venue event journaling, the cloud-side Venue Edge enrollment plus bootstrap or journal-sync contract, and the shared platform integrations with Auth, MDM, Nexus, Nodo, Pay, and Venue Survey.

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:

srv_topolo_commerce

API key scopes

dashboard.read

View Commerce dashboards and venue summaries

Resource pattern: none

venues.read

View venue configuration and cross-venue state

Resource pattern: none

venues.write

Manage venue configuration and assignments

Resource pattern: none

settings.read

View org and venue module settings

Resource pattern: none

settings.write

Manage org defaults, venue overrides, and presets

Resource pattern: none

catalog.read

View catalog, menu, and service content

Resource pattern: none

catalog.write

Manage catalog, menu, and service content

Resource pattern: none

imports.read

View import jobs and review queues

Resource pattern: none

imports.write

Create import jobs and approve publish revisions

Resource pattern: none

queues.read

View queue lanes, kitchen flow, and dispatch state

Resource pattern: none

queues.write

Manage queue transitions and operator actions

Resource pattern: none

service_requests.read

View service requests and bookings

Resource pattern: none

service_requests.write

Manage service requests and bookings

Resource pattern: none

payments.create

Create Commerce payment sessions

Resource pattern: none

devices.read

View MDM-linked device assignments

Resource pattern: none

devices.write

Manage MDM-linked device assignments

Resource pattern: none

publishing.read

View DOOH publishing state and artifacts

Resource pattern: none

publishing.write

Manage DOOH publishing and venue boards

Resource pattern: none

reports.read

View Commerce reporting and venue performance

Resource pattern: none

Service permissions

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

Data Ownership

Binding: COMMERCE_DB

Target: 21adec83-53ba-46ba-9b93-e3f6c028a566

Environment: default

Source: PlatformApplications/TopoloCommerce/apps/api/wrangler.toml

Binding: COMMERCE_ASSETS

Target: topolo-commerce-prod-r2-assets

Environment: default

Source: PlatformApplications/TopoloCommerce/apps/api/wrangler.toml

Queues / Cron / Workflows

Queue bindings:

No queue bindings were detected.

Cron triggers

No cron triggers were detected.

Workflow signals

No explicit queue/workflow script or cron signal was discovered.

Environment Variables and Bindings

Environment variables:

CORS_ORIGINS ENVIRONMENT TOPOLO_AUTH_URL

All wrangler bindings

COMMERCE_DB (d1) -> 21adec83-53ba-46ba-9b93-e3f6c028a566
COMMERCE_ASSETS (r2) -> topolo-commerce-prod-r2-assets

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: no explicit setting found

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

Build and deploy commands

build — PlatformApplications/TopoloCommerce/apps/api/package.json :: node --check src/index.js
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 && 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 && wrangler pages deploy dist --project-name topolo-commerce-ops-web
build:api — PlatformApplications/TopoloCommerce/package.json :: npm --workspace @topolo/commerce-api run build
build:ops — PlatformApplications/TopoloCommerce/package.json :: npm --workspace @topolo/commerce-ops-web run build
build:guest — PlatformApplications/TopoloCommerce/package.json :: npm --workspace @topolo/commerce-guest-web run build

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/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/package.json
PlatformApplications/TopoloCommerce/packages/shared/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-10

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