application public active Verified 2026-04-29

TopoloOne

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.

Documentation Map

What It Is

Canonical documentation for TopoloOne lives in `PlatformApplications/TopoloDocs`.

Use this repository for implementation only. Local product and operational docs have been retired in favor of the docs application.

Architecture

Owners: platform-experience

Source repos: PlatformApplications/TopoloOne, PlatformApplications/TopoloOne/apps/mobile, PlatformApplications/TopoloOne/packages/topolo_mobile_core

Dependencies: topolo-auth, topolo-nexus, topolo-developers, topolo-p2p, applications-packages

Repo shape

PlatformApplications/TopoloOne/AGENTS.md
PlatformApplications/TopoloOne/README.md
PlatformApplications/TopoloOne/apps/
PlatformApplications/TopoloOne/cloudcontrol-deployment-report-ai-chat-rag.json
PlatformApplications/TopoloOne/cloudcontrol-deployment-report-topoloone-worker.json
PlatformApplications/TopoloOne/commitlint.config.js
PlatformApplications/TopoloOne/docs/
PlatformApplications/TopoloOne/lighthouserc.js
PlatformApplications/TopoloOne/migration.config.ts
PlatformApplications/TopoloOne/package.json
PlatformApplications/TopoloOne/packages/
PlatformApplications/TopoloOne/playwright-report/
PlatformApplications/TopoloOne/playwright.config.ts
PlatformApplications/TopoloOne/pnpm-lock.yaml
PlatformApplications/TopoloOne/pnpm-workspace.yaml
PlatformApplications/TopoloOne/scripts/
PlatformApplications/TopoloOne/test-results/
PlatformApplications/TopoloOne/tests/
PlatformApplications/TopoloOne/topolo.cloudcontrol.json
PlatformApplications/TopoloOne/apps/mobile/README.md

Runtime Surfaces

Hosts:

https://one.topolo.app https://topolo.io https://one.topolo.io ios-app://io.topolo.topolo_one android-app://io.topolo.topolo_one

ai-chat-rag

Config: PlatformApplications/TopoloOne/apps/ai-chat-rag/wrangler.toml

Main: dist/index.js

Routes: workers.dev or asset-only surface

topoloone

Config: PlatformApplications/TopoloOne/apps/dashboard-web/wrangler.toml

Main: not declared

Routes: workers.dev or asset-only surface

topoloone-worker

Config: PlatformApplications/TopoloOne/apps/dashboard-worker/wrangler.toml

Main: dist/index.js

Routes: one.stg.topolo.us, one.topolo.app/*

topoloone-website

Config: PlatformApplications/TopoloOne/apps/marketing-site/wrangler.toml

Main: worker/index.js

Routes: stg.topolo.us

API Reference

Coverage: curated

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

Source exists in repo: yes

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, workspace context and membership summaries, 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. /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 and forwards only `personal` or `organization` active context into the shared launcher; household is not a peer workspace and instead stays attached to personal context through Auth `selectedHouseholdId` plus `selectedHousehold` with `svc_oneclick_dash` marked `household_capable`. 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. The dashboard /onboarding route starts with mandatory personal recovery-email verification, then completes organization service onboarding for svc_oneclick_dash through Auth's service onboarding route, 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. 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 org-first categories and collections that do not apply outside personal or family use. The marketing worker adds public checkout, waitlist, demo-booking, 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. 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 to request-based demo or sales contact 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 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:

svc_oneclick_dash

API key scopes

api_keys.write

Manage Topolo One machine credentials

Resource pattern: none

apps.read

View application catalog

Resource pattern: none

apps.write

Manage applications and deployments

Resource pattern: none

dashboard.read

View OneClick dashboard

Resource pattern: none

launches.read

Generate or inspect launch flows

Resource pattern: none

notifications.read

View notification state

Resource pattern: none

notifications.write

Manage notification subscriptions

Resource pattern: none

settings.read

View system settings

Resource pattern: none

settings.write

Manage system configuration

Resource pattern: none

widgets.read

Read widget and summary data

Resource pattern: none

workflows.read

View automation workflows

Resource pattern: none

workflows.write

Create and edit workflows

Resource pattern: none

Service permissions

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

Data Ownership

Binding: CHAT_CACHE

Target: 5ee16c92ffe34626aacbe45b94e416fe

Environment: default

Source: PlatformApplications/TopoloOne/apps/ai-chat-rag/wrangler.toml

Binding: CHAT_CACHE

Target: 5ee16c92ffe34626aacbe45b94e416fe

Environment: preview

Source: PlatformApplications/TopoloOne/apps/ai-chat-rag/wrangler.toml

Binding: CHAT_CACHE

Target: 5ee16c92ffe34626aacbe45b94e416fe

Environment: production

Source: PlatformApplications/TopoloOne/apps/ai-chat-rag/wrangler.toml

Binding: ONECLICK_DB

Target: ace6619b-0dae-4248-870b-71561d9087e2

Environment: default