Topolo Support

Public overview of the Topolo support platform for internal operations and customer-organization ticket workflows.

publicverified 2026-08-01supportticketsauth

What It Is

Topolo Support is the support platform for the Topolo ecosystem, used for both Topolo internal support operations and customer-organization ticket workflows.

Architecture

The application is a standalone Worker-hosted frontend at support.topolo.app. It relies on Topolo Auth for sign-in and requester-context reads, while ticket workflow state lives in the app’s own support-owned D1 schema. Public entry now uses the shared Auth-managed landing and login pages, and the signed console now uses the shared first-party shell and browser auth packages from topolo-platform/packages instead of active Support-local copies. The signed desk now follows the same responsive shared shell pattern as the other first-party apps, including the shared launcher and local command palette surfaces. The shared public copy, provider visibility, and accent colors for Support are Auth-owned configuration associated with the topolo-support service, and the same-origin /api/auth/* gateway is also the required path for shared launcher catalog reads. Signed access is tenant-scoped through explicit support workspaces and inboxes: Topolo operators can switch across workspaces, org operators can work only their own organization workspace, and requester-grade users can create and follow only their own public ticket threads. Support also keeps its own activity ledger, outbound notification outbox, signed inbound webhook ledger, and app-owned channel routing/sync state so ticket creation, replies, assignment changes, and provider callbacks remain auditable. Nexus owns the connected provider identity, lifecycle, errors, and credentials; Support retains only the stable Nexus reference and hydrates those fields live. A scheduled Worker retry loop now re-attempts due queued or failed notifications with backoff, so customer-facing delivery does not depend on a currently signed-in operator.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

The primary runtime host is https://support.topolo.app, with a staging mirror at https://support.stg.topolo.us, public entry routes at / and /login, and signed routes for /tickets, /tickets/:ticketId, and /macros.

API Reference

Topolo Support owns a dedicated /api/support/* route family for workspace context, tickets, messages, per-ticket notification dispatch, and signed inbound webhook ingestion. Auth remains the source of truth for identity and service access only, and Nexus is the outbound email delivery layer for queued Support notifications.

Auth and Permissions

Topolo Support uses the shared Topolo browser auth client and Auth-managed service access under the canonical app id app_topolo_support in every environment. The Worker receives that id through APP_ID, injects it into the served HTML shell, and backend routes use the same binding before setting X-App-ID; staging seed routes separately use TOPOLO_SEED_APP_ID=app_topolo_seed. Browser login URL construction and callback completion delegate to the shared auth client, including one-time sso_code redemption; direct bearer-token callback URLs, /sso?token= bridge routes, and app-local /sso/exchange parser code are not supported.

Data Ownership

Topolo Support owns support workspaces, inbox metadata, tickets, message history, inbound webhook audit state, activity history, queued notification intents plus retry state, assignment state, SLA tracking, and workspace-scoped macros. Topolo Auth owns identity, organization, permission, and launcher metadata only, and Topolo Nexus owns the downstream email-provider delivery hop.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /tickets, its offline policy is read_through_cache, and it requires organization context.

Published permissions: tickets:read, tickets:write, macros:read, macros:write.

  • /tickets uses /api/support/tickets with the record.list template and support.tickets.list data source.
  • /tickets/:id uses /api/support/tickets/:id with the record.detail template and support.tickets.detail data source.
  • /macros uses /api/support/macros with the record.list template and support.macros.list data source.
  • /macros/:id uses /api/support/macros/:id with the record.detail template and support.macros.detail data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Topolo Support deploys as the Cloudflare Worker topolo-support on support.topolo.app. Its staging mirror deploys separately as topolo-support-staging on support.stg.topolo.us, with staging builds injecting staging Auth and portal hosts.

Failure Modes

  • the wrong Worker deployment or route serves support.topolo.app
  • the support-owned D1 binding is missing or misconfigured
  • the app bypasses Auth for requester context and drifts from the canonical identity source of truth
  • signed inbound provider calls reach Support without the configured webhook secret or with an invalid signature
  • queued outbound notifications cannot leave Support because no Nexus sender profile is available, the Support-to-Nexus service token is mismatched, or automated retries are not running
  • staging was deployed from a stale dist/ bundle or without staging Auth/portal build variables

Debugging

Start with /systems/topolo-support, then verify the Worker deployment, support D1 binding, Auth session/context reads, inbound webhook audit rows, queued notification delivery metadata, and retry timestamps.

Use It

Open Topolo Support for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-support --json
topolo actions --service topolo-support --json
topolo actions capabilities --service topolo-support --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Topolo Support and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Reconciled canonical Nexus connection ownership against apps/TopoloSupport staging commit bcab37c4e46e on 2026-08-01. Support retains channel routing/sync state and a stable connection reference; Nexus remains the sole provider identity, lifecycle, error, and credential authority.

  • Reconciled the application identity against the manifest, all Wrangler environments, Auth staging, and Auth production on 2026-08-01. All four surfaces resolve topolo-support to app_topolo_support; the retired production-specific id is not canonical documentation.

  • Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found.

  • Verified the native_capability mobile experience contract and its 4 published route(s) against apps/TopoloSupport origin/staging 09b817e10143 on 2026-07-27.

  • Reconciled this page against apps/TopoloSupport origin/staging 9265c60d3a58 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloSupport commits through 3c3beb7; reviewed 85 commits since 2026-06-18, including 3c3beb7 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 2464c68 Stop blocking startup on i18n readiness; ea264b1 Adopt canonical Topolo typography; ced3913 Split Support startup bundle.

  • Replaced runtime Support Auth slug lookups on 2026-05-13 with deployment APP_ID and TOPOLO_SEED_APP_ID bindings so browser auth, shared shell, widget, seed, and backend Auth calls do not call Auth to discover stable app ids.

  • Isolated staging browser builds and runtime upstream requirements on 2026-04-30 so support.stg.topolo.us no longer depends on production Auth, portal, or Nexus fallbacks.

  • Removed the Support app-local login and callback exchange path on 2026-04-18 so sign-in URL construction and /auth/callback code redemption now rely on the shared Topolo browser auth client

  • Added dedicated Support-to-Nexus trusted service auth and scheduled outbox retries on 2026-04-15 so queued or failed customer-facing notifications now back off and retry automatically without relying on a signed-in operator

  • Added signed inbound webhook ingestion and Nexus-backed outbound notification delivery on 2026-04-15 so Support now records provider callbacks, retries queued per-ticket notifications from the signed desk, and hands actual email delivery off to Nexus

  • Added a support-owned communications ledger on 2026-04-15 so ticket creation, workflow updates, and replies now record activity events plus queued requester or agent notifications inside Support’s own data boundary

  • Introduced explicit support workspaces and inboxes on 2026-04-15 so customer organizations now land in a concrete workspace and inbox model instead of relying only on tenant-filtered queues, and workspace switching now drives which queue and macros the signed desk uses

  • Hardened Topolo Support to a tenant-scoped queue model on 2026-04-15 so signed users now see only the queues and replies appropriate to their Topolo or organization role, with guest/requester users limited to their own public ticket threads

  • Corrected the signed Support shell on 2026-04-15 so the app now follows the same responsive shared first-party shell composition and local command palette contract as the other Topolo apps instead of keeping a Support-local signed layout inside the shell container

  • Corrected the shared Support experience contract on 2026-04-15 so Auth now serves Support-specific landing/login copy and readable shared color tokens, while the local /api/auth/* gateway correctly forwards shared launcher catalog reads instead of returning 404s

  • Standardized Topolo Support public entry on the shared landing and login surfaces on 2026-04-15 so unauthenticated visitors now enter through the Auth-managed shared pages instead of a Support-specific public shell

  • Standardized Topolo Support on the shared first-party shell and browser package contract on 2026-04-15 so the signed desk now uses the shared launcher/shell/auth surfaces instead of the old Support-local package copies in the active build path

  • Created Topolo Support on 2026-04-13 as the dedicated internal support desk, replacing the old Admin placeholder route with a standalone application boundary

  • Switched Topolo Support to a Worker-with-assets deployment on 2026-04-13 after the Pages asset layer proved unreliable in production