{
  "generated_at": "2026-04-10T10:04:35.552Z",
  "system": {
    "id": "topolo-commerce",
    "name": "TopoloCommerce",
    "slug": "topolo-commerce",
    "kind": "application",
    "summary": "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.",
    "aliases": [],
    "lifecycle": "active",
    "last_verified": "2026-04-10",
    "owners": [
      "commerce"
    ],
    "repo_paths": [
      "PlatformApplications/TopoloCommerce"
    ],
    "service_ids": [
      "srv_topolo_commerce"
    ],
    "visibility": "public",
    "api_contract": {
      "type": "curated",
      "source": "PlatformApplications/TopoloDocs/src/content/public/applications/commerce.mdx",
      "notes": "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."
    },
    "primary_hosts": [
      "https://commerce.topolo.app"
    ],
    "doc_paths": [
      "applications/commerce",
      "internal/apps/commerce",
      "internal/apps/commerce-design",
      "internal/apps/commerce-modules",
      "internal/apps/commerce-resilience"
    ],
    "dependencies": [
      "topolo-auth",
      "topolo-mdm",
      "topolo-nexus",
      "topolo-nodo",
      "topolo-pay",
      "topolo-venue-survey"
    ],
    "public_hub_url": "/systems/topolo-commerce",
    "internal_hub_url": "/internal/systems/topolo-commerce",
    "application_api_url": "/reference/apps/topolo-commerce",
    "generated_openapi_url": null,
    "machine_urls": {
      "system": "/machine/systems/topolo-commerce.json",
      "application": "/machine/applications/topolo-commerce.json"
    }
  },
  "docs": {
    "public": [
      {
        "id": "applications/commerce.mdx",
        "title": "TopoloCommerce",
        "summary": "Public overview of the multi-vertical commerce platform for venue operations, guest runtimes, and staff execution.",
        "audience": "public",
        "tags": [
          "commerce",
          "venues",
          "kiosk"
        ],
        "url": "/applications/commerce.mdx",
        "last_verified": "2026-04-10"
      }
    ],
    "internal": [
      {
        "id": "apps/commerce-design.mdx",
        "title": "TopoloCommerce Design Appendix",
        "summary": "Design appendix for TopoloCommerce covering the required Topolo design-language contract, mobile behavior, and the Apple-style simplicity layer allowed for guest and staff flows.",
        "audience": "internal",
        "tags": [
          "commerce",
          "design",
          "mobile"
        ],
        "url": "/internal/apps/commerce-design.mdx",
        "last_verified": "2026-04-10"
      },
      {
        "id": "apps/commerce-modules.mdx",
        "title": "TopoloCommerce Module Contract",
        "summary": "Internal module contract for TopoloCommerce covering org defaults, venue overrides, preset resolution, and module-aware route visibility across staff and guest surfaces.",
        "audience": "internal",
        "tags": [
          "commerce",
          "modules",
          "tenancy"
        ],
        "url": "/internal/apps/commerce-modules.mdx",
        "last_verified": "2026-04-10"
      },
      {
        "id": "apps/commerce-resilience.mdx",
        "title": "TopoloCommerce Resilience",
        "summary": "Internal resilience architecture and current implementation status for cached venue operation, local outbox replay, and the phased path toward Venue Edge and controlled 5G rescue uplink.",
        "audience": "internal",
        "tags": [
          "commerce",
          "offline",
          "resilience",
          "venue"
        ],
        "url": "/internal/apps/commerce-resilience.mdx",
        "last_verified": "2026-04-10"
      },
      {
        "id": "apps/commerce.mdx",
        "title": "TopoloCommerce Handbook",
        "summary": "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.",
        "audience": "internal",
        "tags": [
          "commerce",
          "venues",
          "modules",
          "kiosk"
        ],
        "url": "/internal/apps/commerce.mdx",
        "last_verified": "2026-04-10"
      }
    ],
    "runbooks": [
      {
        "id": "runbooks/api-key-scope-mismatches.mdx",
        "title": "API Key Scope Mismatches",
        "summary": "Runbook for when TopoloOne or an app shows the wrong API key scopes, no scopes, or unexpected scope drift.",
        "url": "/internal/runbooks/api-key-scope-mismatches.mdx"
      },
      {
        "id": "runbooks/auth-session-and-role-drift.mdx",
        "title": "Auth Session and Role Drift",
        "summary": "Runbook for stale role claims, incorrect admin gating, and mismatches between live org roles and token claims.",
        "url": "/internal/runbooks/auth-session-and-role-drift.mdx"
      },
      {
        "id": "runbooks/cors-and-cross-origin-failures.mdx",
        "title": "CORS and Cross-Origin Failures",
        "summary": "Runbook for preflight failures, wrong API origins, and wildcard-origin credential issues.",
        "url": "/internal/runbooks/cors-and-cross-origin-failures.mdx"
      },
      {
        "id": "runbooks/stale-deploy-and-cache-issues.mdx",
        "title": "Stale Deploy and Cache Issues",
        "summary": "Runbook for old bundles, wrong host delivery, stale service workers, and mismatched Pages/worker routes.",
        "url": "/internal/runbooks/stale-deploy-and-cache-issues.mdx"
      },
      {
        "id": "runbooks/resource-binding-sync-failures.mdx",
        "title": "Resource Binding Sync Failures",
        "summary": "Runbook for missing bindable resources such as brands or workspaces in the API key form.",
        "url": "/internal/runbooks/resource-binding-sync-failures.mdx"
      }
    ]
  },
  "authority": {
    "owners": [
      "commerce"
    ],
    "repo_paths": [
      "PlatformApplications/TopoloCommerce"
    ],
    "service_ids": [
      "srv_topolo_commerce"
    ],
    "dependencies": [
      "topolo-auth",
      "topolo-mdm",
      "topolo-nexus",
      "topolo-nodo",
      "topolo-pay",
      "topolo-venue-survey"
    ],
    "aliases": []
  },
  "interfaces": {
    "contract_type": "curated",
    "contract_source": "PlatformApplications/TopoloDocs/src/content/public/applications/commerce.mdx",
    "contract_source_exists": true,
    "openapi": null,
    "readme": {
      "path": "PlatformApplications/TopoloCommerce/README.md",
      "intro": [
        "TopoloCommerce is the multi-vertical commerce workspace for the Topolo platform.",
        "Current v1 surfaces:",
        "This scaffold follows the canonical docs in `PlatformApplications/TopoloDocs`."
      ],
      "headings": [
        "TopoloCommerce"
      ],
      "routeHighlights": [],
      "commandHighlights": []
    }
  },
  "auth": {
    "depends_on_topolo_auth": true,
    "api_key_scopes": [
      {
        "name": "dashboard.read",
        "description": "View Commerce dashboards and venue summaries",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "venues.read",
        "description": "View venue configuration and cross-venue state",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "venues.write",
        "description": "Manage venue configuration and assignments",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "settings.read",
        "description": "View org and venue module settings",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "settings.write",
        "description": "Manage org defaults, venue overrides, and presets",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "catalog.read",
        "description": "View catalog, menu, and service content",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "catalog.write",
        "description": "Manage catalog, menu, and service content",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "imports.read",
        "description": "View import jobs and review queues",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "imports.write",
        "description": "Create import jobs and approve publish revisions",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "queues.read",
        "description": "View queue lanes, kitchen flow, and dispatch state",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "queues.write",
        "description": "Manage queue transitions and operator actions",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "service_requests.read",
        "description": "View service requests and bookings",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "service_requests.write",
        "description": "Manage service requests and bookings",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "payments.create",
        "description": "Create Commerce payment sessions",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "devices.read",
        "description": "View MDM-linked device assignments",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "devices.write",
        "description": "Manage MDM-linked device assignments",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "publishing.read",
        "description": "View DOOH publishing state and artifacts",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "publishing.write",
        "description": "Manage DOOH publishing and venue boards",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "name": "reports.read",
        "description": "View Commerce reporting and venue performance",
        "resourcePattern": null,
        "kind": "api_key_scope"
      }
    ],
    "service_permissions": [
      {
        "name": "dashboard:read",
        "description": "View Commerce dashboards and venue summaries",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "venues:read",
        "description": "View venue configuration and cross-venue state",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "venues:write",
        "description": "Manage venue configuration and assignments",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "settings:read",
        "description": "View org and venue module settings",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "settings:write",
        "description": "Manage org defaults, venue overrides, and presets",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "catalog:read",
        "description": "View catalog, menu, and service content",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "catalog:write",
        "description": "Manage catalog, menu, and service content",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "imports:read",
        "description": "View import jobs and review queues",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "imports:write",
        "description": "Create import jobs and approve publish revisions",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "queues:read",
        "description": "View queue lanes, kitchen flow, and dispatch state",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "queues:write",
        "description": "Manage queue transitions and operator actions",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "service_requests:read",
        "description": "View service requests and bookings",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "service_requests:write",
        "description": "Manage service requests and bookings",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "payments:create",
        "description": "Create Commerce payment sessions",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "devices:read",
        "description": "View MDM-linked device assignments",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "devices:write",
        "description": "Manage MDM-linked device assignments",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "publishing:read",
        "description": "View DOOH publishing state and artifacts",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "publishing:write",
        "description": "Manage DOOH publishing and venue boards",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "name": "reports:read",
        "description": "View Commerce reporting and venue performance",
        "resourcePattern": null,
        "kind": "permission"
      }
    ]
  },
  "runtime": {
    "primary_hosts": [
      "https://commerce.topolo.app"
    ],
    "repo_entries": [
      "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"
    ],
    "wrangler_surfaces": [
      {
        "path": "PlatformApplications/TopoloCommerce/apps/api/wrangler.toml",
        "observabilityEnabled": false,
        "environments": [],
        "routes": [],
        "vars": [
          "CORS_ORIGINS",
          "ENVIRONMENT",
          "TOPOLO_AUTH_URL"
        ],
        "bindings": [
          {
            "kind": "d1",
            "binding": "COMMERCE_DB",
            "sourcePath": "PlatformApplications/TopoloCommerce/apps/api/wrangler.toml",
            "target": "21adec83-53ba-46ba-9b93-e3f6c028a566"
          },
          {
            "kind": "r2",
            "binding": "COMMERCE_ASSETS",
            "sourcePath": "PlatformApplications/TopoloCommerce/apps/api/wrangler.toml",
            "target": "topolo-commerce-prod-r2-assets"
          }
        ],
        "cronTriggers": [],
        "workerName": "topolo-commerce-api",
        "main": "src/index.js",
        "compatibilityDate": "2026-04-09"
      },
      {
        "path": "PlatformApplications/TopoloCommerce/apps/guest-web/wrangler.toml",
        "observabilityEnabled": false,
        "environments": [],
        "routes": [],
        "vars": [],
        "bindings": [],
        "cronTriggers": [],
        "workerName": "topolo-commerce-guest-web",
        "compatibilityDate": "2026-04-09"
      },
      {
        "path": "PlatformApplications/TopoloCommerce/apps/ops-web/wrangler.toml",
        "observabilityEnabled": false,
        "environments": [],
        "routes": [],
        "vars": [],
        "bindings": [],
        "cronTriggers": [],
        "workerName": "topolo-commerce-ops-web",
        "compatibilityDate": "2026-04-09"
      }
    ],
    "packages": [
      {
        "path": "PlatformApplications/TopoloCommerce/apps/api/package.json",
        "name": "@topolo/commerce-api",
        "scripts": [
          "dev",
          "build",
          "deploy",
          "test"
        ],
        "scriptCommands": [
          {
            "name": "dev",
            "command": "wrangler dev"
          },
          {
            "name": "build",
            "command": "node --check src/index.js"
          },
          {
            "name": "deploy",
            "command": "wrangler deploy"
          },
          {
            "name": "test",
            "command": "node --test ./test/api.test.mjs"
          }
        ]
      },
      {
        "path": "PlatformApplications/TopoloCommerce/apps/guest-web/package.json",
        "name": "@topolo/commerce-guest-web",
        "scripts": [
          "dev",
          "build",
          "preview",
          "deploy"
        ],
        "scriptCommands": [
          {
            "name": "dev",
            "command": "vite"
          },
          {
            "name": "build",
            "command": "vite build"
          },
          {
            "name": "preview",
            "command": "vite preview"
          },
          {
            "name": "deploy",
            "command": "npm run build && wrangler pages deploy dist --project-name topolo-commerce-guest-web"
          }
        ]
      },
      {
        "path": "PlatformApplications/TopoloCommerce/apps/ops-web/package.json",
        "name": "@topolo/commerce-ops-web",
        "scripts": [
          "dev",
          "build",
          "preview",
          "deploy"
        ],
        "scriptCommands": [
          {
            "name": "dev",
            "command": "vite"
          },
          {
            "name": "build",
            "command": "vite build"
          },
          {
            "name": "preview",
            "command": "vite preview"
          },
          {
            "name": "deploy",
            "command": "npm run build && wrangler pages deploy dist --project-name topolo-commerce-ops-web"
          }
        ]
      },
      {
        "path": "PlatformApplications/TopoloCommerce/package.json",
        "name": "topolo-commerce",
        "description": "TopoloCommerce multi-vertical commerce workspace",
        "scripts": [
          "dev:api",
          "dev:ops",
          "dev:guest",
          "build:api",
          "build:ops",
          "build:guest",
          "test"
        ],
        "scriptCommands": [
          {
            "name": "dev:api",
            "command": "npm --workspace @topolo/commerce-api run dev"
          },
          {
            "name": "dev:ops",
            "command": "npm --workspace @topolo/commerce-ops-web run dev"
          },
          {
            "name": "dev:guest",
            "command": "npm --workspace @topolo/commerce-guest-web run dev"
          },
          {
            "name": "build:api",
            "command": "npm --workspace @topolo/commerce-api run build"
          },
          {
            "name": "build:ops",
            "command": "npm --workspace @topolo/commerce-ops-web run build"
          },
          {
            "name": "build:guest",
            "command": "npm --workspace @topolo/commerce-guest-web run build"
          },
          {
            "name": "test",
            "command": "npm --workspace @topolo/commerce-shared run test && npm --workspace @topolo/commerce-api run test"
          }
        ]
      },
      {
        "path": "PlatformApplications/TopoloCommerce/packages/shared/package.json",
        "name": "@topolo/commerce-shared",
        "scripts": [
          "test"
        ],
        "scriptCommands": [
          {
            "name": "test",
            "command": "node --test ./test/modules.test.mjs"
          }
        ]
      }
    ]
  },
  "data": {
    "env_vars": [
      "CORS_ORIGINS",
      "ENVIRONMENT",
      "TOPOLO_AUTH_URL"
    ],
    "bindings": [
      {
        "kind": "d1",
        "binding": "COMMERCE_DB",
        "sourcePath": "PlatformApplications/TopoloCommerce/apps/api/wrangler.toml",
        "target": "21adec83-53ba-46ba-9b93-e3f6c028a566"
      },
      {
        "kind": "r2",
        "binding": "COMMERCE_ASSETS",
        "sourcePath": "PlatformApplications/TopoloCommerce/apps/api/wrangler.toml",
        "target": "topolo-commerce-prod-r2-assets"
      }
    ],
    "queue_bindings": [],
    "storage_kinds": [
      "d1",
      "r2"
    ],
    "workflow_signals": []
  },
  "deployment": {
    "commands": [
      {
        "name": "build",
        "command": "PlatformApplications/TopoloCommerce/apps/api/package.json :: node --check src/index.js"
      },
      {
        "name": "deploy",
        "command": "PlatformApplications/TopoloCommerce/apps/api/package.json :: wrangler deploy"
      },
      {
        "name": "build",
        "command": "PlatformApplications/TopoloCommerce/apps/guest-web/package.json :: vite build"
      },
      {
        "name": "preview",
        "command": "PlatformApplications/TopoloCommerce/apps/guest-web/package.json :: vite preview"
      },
      {
        "name": "deploy",
        "command": "PlatformApplications/TopoloCommerce/apps/guest-web/package.json :: npm run build && wrangler pages deploy dist --project-name topolo-commerce-guest-web"
      },
      {
        "name": "build",
        "command": "PlatformApplications/TopoloCommerce/apps/ops-web/package.json :: vite build"
      },
      {
        "name": "preview",
        "command": "PlatformApplications/TopoloCommerce/apps/ops-web/package.json :: vite preview"
      },
      {
        "name": "deploy",
        "command": "PlatformApplications/TopoloCommerce/apps/ops-web/package.json :: npm run build && wrangler pages deploy dist --project-name topolo-commerce-ops-web"
      },
      {
        "name": "build:api",
        "command": "PlatformApplications/TopoloCommerce/package.json :: npm --workspace @topolo/commerce-api run build"
      },
      {
        "name": "build:ops",
        "command": "PlatformApplications/TopoloCommerce/package.json :: npm --workspace @topolo/commerce-ops-web run build"
      },
      {
        "name": "build:guest",
        "command": "PlatformApplications/TopoloCommerce/package.json :: npm --workspace @topolo/commerce-guest-web run build"
      }
    ],
    "routes": [],
    "environments": [],
    "assets_directories": [],
    "observability_enabled": false
  },
  "debugging": {
    "failure_modes": [],
    "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"
    ]
  }
}