TopoloCommerce Module Contract

What It Is

This page defines the module-resolution contract for TopoloCommerce.

The platform must support mixed venue portfolios under one org, so route visibility and UI affordances cannot be hardcoded to one vertical.

Architecture

TopoloCommerce copies the CRM module-settings pattern into a commerce-specific shape.

Canonical settings layers:

• org defaults in commerce_org_settings
• venue overrides in commerce_venue_settings
• preset definitions in PlatformApplications/TopoloCommerce/packages/shared/src/modules.js
• dependency resolution in the same shared module helper

V1 module collections are:

• shared_core
• shared_workflows
• hospitality
• retail
• service

V1 presets are:

• core_only
• hospitality_standard
• retail_standard
• service_standard
• hybrid_venue

Runtime Surfaces

The effective module contract must drive all three operator and guest surfaces:

• apps/api exposes module metadata and effective resolution routes
• apps/ops-web hides or shows navigation and route content based on effective venue module state, including the resilience surface exposed by the new resilience shared-workflow module
• apps/guest-web renders only the guest-facing flows enabled for the venue
• apps/guest-mobile mirrors the same venue-aware module logic on managed devices

API Reference

The canonical implementation lives in:

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

Important helpers:

• buildDefaultModuleSettings
• buildPresetModuleSettings
• mergeModuleSettings
• resolveModuleSettingsDependencies
• getEnabledModuleKeys
• getEnabledCollections
• isModuleEnabled

Auth and Permissions

Module settings do not replace auth.

• staff routes still require Auth-backed staff permission checks
• module state decides whether a route should exist in the venue context after auth succeeds
• guest runtimes should resolve venue module state without depending on human Topolo auth

Data Ownership

TopoloCommerce owns the effective module settings contract for its own routes and venue surfaces.

That includes:

• org defaults
• venue overrides
• preset selection
• dependency resolution
• route visibility decisions in ops and guest surfaces

Deployments

Every deployed Commerce surface must use the same shared module contract so a venue behaves consistently across:

• Worker routes
• ops web navigation
• guest web runtime
• guest mobile kiosk runtime

Failure Modes

• venue overrides are treated as a different schema than org defaults
• presets bypass dependency resolution
• ops navigation and guest runtime resolve different effective module states for the same venue
• one org with many venues accidentally behaves like a single-venue tenancy model
• module visibility decisions are copied into app-local conditionals instead of the shared helper
• the resilience route is deployed but not governed by the same shared module contract as the rest of ops

Debugging

• start with PlatformApplications/TopoloCommerce/packages/shared/src/modules.js
• compare the effective venue module object used by the API and the browser runtimes
• confirm the selected preset before debugging venue overrides
• confirm dependency resolution before treating a missing route as a browser-only issue

Change Log / Verification

• Added the canonical TopoloCommerce module contract on 2026-04-10 and aligned it to the CRM-style org-default plus venue-override resolution model
• Updated the canonical TopoloCommerce module contract on 2026-04-10 to include the resilience shared-workflow module and its module-aware ops surface