Topolo Quro

Public overview of the QR creation, redirect, analytics, and authenticated UI surface in the Topolo portfolio.

publicverified 2026-07-29qrredirectsanalytics

What It Is

Topolo Quro is the QR creation, redirect, and scan-tracking application in the Topolo portfolio.

Architecture

The current repo shape includes an API worker, a redirect worker, a canonical modern UI, and a retained legacy UI used only for reference and parity checks.

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

Use /systems/topolo-quro for the current deployment inventory and service metadata.

API Reference

The active contract centers on QR creation, templates, analytics, redirect resolution, and org-scoped authenticated browser flows.

Auth and Permissions

The canonical current UI uses the first-party Topolo auth pattern with authenticated routes, branded embedded password login on quro.topolo.app, and callback flows. The legacy UI should not be treated as the active auth model. Protected Quro API bearer-token requests validate through Auth and do not accept locally decoded JWT claims from a Worker secret. Browser SSO callbacks delegate one-time sso_code redemption to the shared @topolo-io/auth-client package, so callback URLs carry short-lived codes rather than bearer tokens or /sso?token= bridge payloads. The canonical browser UI keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal reload should reopen the authenticated dashboard rather than appearing signed out. Quro now also normalizes any missing Auth role claim to member in both the canonical browser UI and API worker bootstrap.

Data Ownership

Quro owns QR assets, redirect mappings, analytics, and related org-scoped settings and dashboards.

Mobile Experience

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

Published permissions: codes:read, codes:write, series:read, analytics:read.

  • /dashboard uses /qurocodes with the record.list template and quro.codes.list data source.
  • /codes/:slug uses /qurocodes/:slug with the record.detail template and quro.codes.detail data source.
  • /series uses /series with the record.list template and quro.series.list data source.
  • /series/:id/dashboard uses /series/:id/dashboard with the record.detail template and quro.series.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

Deploy Quro as a cluster of API, redirect, and authenticated UI surfaces. Treat the legacy UI as reference-only.

Failure Modes

  • legacy UI behavior is mistaken for the live product contract
  • redirect and analytics behavior drifts from the authenticated create/manage surface
  • auth flows are documented from the wrong UI generation

Debugging

Start with /systems/topolo-quro, then confirm whether the failing behavior belongs to the canonical UI, redirect worker, or API worker.

Use It

Open Topolo Quro 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-quro --json
topolo actions --service topolo-quro --json
topolo actions capabilities --service topolo-quro --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 Quro 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

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

  • Reconciled this page against apps/TopoloQuro origin/staging 7d86ee338645 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/TopoloQuro commits through 77b27b1; reviewed 360 commits since 2026-05-14, including 77b27b1 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); df339d0 Adopt canonical Topolo typography; d24b3eb Lazy load Quro startup surfaces; 8dc6375 Roll out ui-kit capture startup split.

  • Enabled same-tab browser session restore by default on 2026-04-23 so Quro reloads remain signed in after successful Auth handoff or refresh.

  • Corrected Quro role normalization on 2026-04-24 so missing Auth role claims resolve to member in both the canonical UI and API worker bootstrap.

  • Verified the canonical Quro branded password-login completion path on 2026-04-21 so first-party sign-in remains on the app origin after shared Auth persists the session.

  • Removed the Quro API worker's residual local JWT_SECRET handoff on 2026-04-18 so protected bearer-token requests validate through Auth.

  • Removed the canonical Quro /sso?token= browser bridge on 2026-04-18 so /auth/callback now relies on the shared Topolo browser auth client for code redemption

  • Added canonical Topolo Quro coverage and retired repo-local Quro docs on 2026-03-30

  • Promoted canonical Quro browser SSO callbacks to Auth /sso/exchange on 2026-04-17 so callback URLs require a one-time sso_code instead of bearer tokens