TopoloOne

Documentation Map

• Application hub
• Application API surface
• Machine system JSON
• Machine application JSON
• applications/one

What It Is

Unified personal and organization live workspace, personal-profile family management, authenticated app catalog, worker-backed pricing, owner-linked subscription billing, content, growth, and developer-acquisition surfaces for TopoloOne.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloOne/apps/dashboard-web/src/lib/api.ts

Source exists in repo: no

The dashboard contract is defined by the Auth-backed client routes it calls, including the app-switcher catalog for installed live-workspace widgets, the same-origin `POST /api/widgets` batch route that fans out server-side to native app `GET /api/widget` endpoints, anonymous Developers-owned store catalog/search/detail routes for the authenticated /apps catalog, Auth service-surface metadata for separating launchable applications from technical services, active-context routing, selected-household state for personal-profile family flows, backend launcher preferences, app commerce metadata, org-user install assignment data, household-management routes, API-key management routes, Auth recovery-email status through `/api/auth/me/recovery-email`, and the TopoloNotify-backed `/actions` queue. Worker-fronted dashboard shell routes strip inbound Cloudflare loop/proxy headers before fetching the Pages origin so `one.topolo.app` and `one.stg.topolo.us` can proxy the dashboard bundle without Cloudflare loop protection blocking the custom host. /dashboard is workspace-only, /apps is the canonical authenticated app catalog, /actions is the full human-required platform action surface, and /store is not a supported alias. The authenticated dashboard uses TopoloAppShell navigationMode=topbar, including shared mobile nav/header behavior, forwards only `personal` or `organization` active context into the shared launcher, keeps the brand lockup to the Topolo mark plus wordmark without the trailing One suffix, and keeps Improve Topolo in the shared account menu rather than the main header; household is not a peer workspace and instead stays attached to personal context through Auth `selectedHouseholdId` plus `selectedHousehold` with the Auth catalog entry for slug `topolo-one` marked `household_capable`. /dashboard must open directly into live workspace widgets without context/status chips, installed-app counts, pinned-count badges, or manual refresh controls above the widget grid because widget refresh is automatic; app-catalog hydration should show widget skeletons rather than an empty shell. The dashboard browser callback delegates Auth SSO one-time sso_code exchange to the shared Auth client and does not accept direct bearer-token callback URLs or expose a legacy `/sso?token=` handoff helper. The dashboard /login route is the first-party embedded password-login surface for One, lands password-authenticated users on /dashboard, and requires /api/auth/me hydration before organization-context users are treated as ready so service onboarding state is available and the login route does not visibly bounce after success. The dashboard /onboarding route starts with mandatory personal recovery-email verification, then completes organization service onboarding through the fixed TopoloOne Auth service id `srv_B6QXlas6w9V0`, and redirects already-complete users back to /dashboard on direct refresh. The widget batch route caches successful native payloads per user and active context for 45 seconds, keeps a five-minute KV stale fallback for degraded app responses, renders metadata-backed overview widgets only when native fetches fail, excludes merely available catalog apps from the live workspace grid so widget fan-out stays scoped to installed context apps, and supports explicit widget-host overrides for apps whose native widget endpoint is not served from the canonical browser origin, including Commerce, Learn, Nexus, Quro, Forecast, Roadmapper, and Socialize. Browser widget launches and shared app-switcher launches must mint Auth SSO handoff codes before opening destination tabs and must surface handoff failures instead of leaving `about:blank` tabs or falling back to unauthenticated app landing pages. The authenticated `/apps` catalog now mirrors the active workspace contract as well: organization context may surface the full business catalog, while personal context must use personal-context Auth access metadata, avoid borrowing an org id, and hide apps without explicit `personal` supported-context or personal-profile household capability metadata. The marketing worker adds public checkout, waitlist, demo-booking, contact/feedback submission, admin-session, owner-linked subscription-webhook ingestion, org billing preview, org billing portal, and internal seat-reconciliation endpoints plus static portfolio and developer acquisition routes. The marketing site dogfoods Topolo Consent through the `topolo-one-marketing` project; the host banner remains local-first, while accept/decline decisions sync analytics, personalization, and advertising purposes through the Consent web SDK, with staging pointed at `https://consent.stg.topolo.us`. Paid checkout carries TopoloOne package metadata for three, five, ten, and everything bundles through Nexus/Stripe; those bundles define paid Topolo app access while third-party apps and customer-built apps remain unlimited through the app store. The free workspace path uses a $1/year Stripe verification subscription and stores completed free-workspace subscriptions separately from paid subscription records. Platform subscription records now live in D1 by `owner_type` and `owner_id`. Public pricing includes the honest 80%-and-growing comparison against mature specialist SaaS stacks, states that each paid seat can be used by a human or one Topolo agent, frames the listed public price as the minimum, routes enterprise pricing through the request-based demo flow for larger rollouts and custom security, compliance, procurement, rollout, or usage needs, and says 50% of paid seat revenue goes directly back into tokens for improving Topolo and its available tools and applications. Public launch CTAs now route to signup or demo requests instead of an inert waitlist button, public roadmap feedback routes to the `/feedback` form backed by `POST /api/contact`, and public social metadata points to `https://x.com/topolotech`, `https://www.instagram.com/topolotech/`, and `https://github.com/Topolo-io`. Public developer CTAs now hand off from TopoloOne into the separate TopoloDevelopers application on developers.topolo.app/signup. The TopoloOne mobile shell at PlatformApplications/TopoloOne/apps/mobile is a Flutter launchpad for iOS and Android that mirrors /dashboard, /apps, /actions, and /settings, but replaces in-app launching with install-aware app-store handoff: tapping a catalog entry first attempts the universal link at one.topolo.app/launch/<serviceId>?code=<one-time-handoff-code> minted from the dashboard worker, falls back to the platform-appropriate App Store or Play Store URL when the target native app is not installed, and falls back to the browser web launch URL when no native build exists. The shared PlatformApplications/TopoloOne/packages/topolo_mobile_core package is the canonical Dart/Flutter implementation of TopoloAuthClient OAuth/PKCE refresh-token storage in the iOS Keychain access group group.io.topolo.shared, the TopoloApi catalog and handoff-code mint client, and the TopoloAppShell wordmark lockup, and is the only place other Topolo Flutter apps adopt platform identity, design tokens, and deep-link reception.

App API page: /reference/apps/topolo-one

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:

API key scopes

Service permissions

api_keys:write, apps:read, apps:write, dashboard:read, entitlements:read, launcher:read, launches:read, notifications:read, notifications:write, settings:read, settings:write, widgets:read, workflows:read, workflows:write

Data Ownership

No storage bindings were derived from wrangler configuration.

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: no explicit setting found

Failure Modes

• No wrangler.toml surface was discovered under the registered repo paths.
• The registered contract source is missing: PlatformApplications/TopoloOne/apps/dashboard-web/src/lib/api.ts
• Neither OpenAPI nor README-derived interface detail was found.

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloOne/apps/dashboard-web/src/lib/api.ts

Change Log / Verification

Lifecycle: active

Last verified: 2026-05-15

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