Topolo Admin

Documentation Map

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

What It Is

Administrative interface for centralized auth, org management, org-scoped role and user-access management, app-centric service assignment, support-facing personal and service-local identity visibility, household-connection context, org billing preview, service controls, audit surfaces, and cross-app handoff into other internal operator tools.

Canonical documentation for Topolo Admin lives in `PlatformApplications/TopoloDocs`.

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

The backend contract backlog for this app is tracked in:

API Reference

Coverage: curated

Source: PlatformApplications/TopoloDocs/src/content/public/applications/admin.mdx

Source exists in repo: yes

Canonical admin coverage now lives in the docs application. Admin first-party embedded password login completes through Admin-owned router navigation after shared Auth token persistence rather than a shared hard document redirect. Admin keeps same-tab sessionStorage access-token restore enabled by default after login and refresh so normal reloads do not appear logged out before cookie refresh completes. Service detail views expose app-centric organization and user assignment or revocation while Auth remains the source of truth for organization-service and user-service access evaluation. User detail views now use Auth's seat-assignment entitlement model for launchable applications: org-included apps stay enabled for everyone, while seat-based apps can be assigned or unassigned by same-org admins only when seats are available. Organization service-assignment views consume Auth service surface metadata so launchable applications are separated from API, runtime, and internal technical services, and the Available Services add flow excludes developer-owned third-party apps marked as organization-internal. Admin now classifies non-org identities from Auth principal metadata plus membership summaries instead of `orgId = null`, treats households as connected personal-account collections rather than separate identity principals, and surfaces Auth-backed org billable-seat summary plus TopoloOne billing preview and billing portal actions in the add-user and organization-detail flows. Admin exposes `GET /api/widget` as a stats widget for TopoloOne live workspace, with platform-admin versus org-admin counts aligned to the Admin dashboard.

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

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

analytics:read, billing:read, billing:write, branding:read, branding:write, dashboard:read, developers:read, developers:write, organizations:read, organizations:write, security:read, security:write, services:read, services:write, settings:read, settings:write, support:read, support:write, system:read, system:write

Data Ownership

No storage bindings were derived from wrangler configuration.

Deployments

Deployment environments: preview

Routes: workers.dev or Pages-only delivery

Observability enabled: yes

Wrangler surfaces

• PlatformApplications/TopoloAdmin/wrangler.toml -> topoloadmin

Build and deploy commands

• build — PlatformApplications/TopoloAdmin/package.json :: tsc && vite build
• build:clean — PlatformApplications/TopoloAdmin/package.json :: rm -rf dist && tsc && vite build
• build:dev — PlatformApplications/TopoloAdmin/package.json :: vite build
• build:staging — PlatformApplications/TopoloAdmin/package.json :: VITE_AUTH_URL=https://auth.stg.topolo.us VITE_AUTH_SERVICE_URL=https://auth.stg.topolo.us VITE_ADMIN_URL=https://topoloadmin-staging.pages.dev VITE_STORE_URL=https://staging.topolo-developers-staging.pages.dev VITE_DEVELOPERS_REVIEW_BASE_URL=https://staging.topolo-developers-staging.pages.dev/review VITE_BUGFIX_API_URL=https://bugfix.stg.topolo.us VITE_SUPPORT_APP_URL=https://support.stg.topolo.us/tickets npm run build
• preview — PlatformApplications/TopoloAdmin/package.json :: vite preview
• deploy — PlatformApplications/TopoloAdmin/package.json :: echo 'Build output ready in ./dist directory'
• deploy:staging — PlatformApplications/TopoloAdmin/package.json :: rm -f node_modules/.cache/wrangler/pages.json node_modules/.cache/wrangler/wrangler-account.json && rm -rf dist && npm run build:staging && env -u CLOUDFLARE_API_TOKEN CLOUDFLARE_ACCOUNT_ID=4f4e1c69a3830946f9fea7b1eb7531ac wrangler pages deploy dist --project-name=topoloadmin-staging --branch=staging --commit-dirty=true

Failure Modes

No default failure-mode heuristics are currently flagged for this system.

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloAdmin/wrangler.toml
• PlatformApplications/TopoloDocs/src/content/public/applications/admin.mdx
• PlatformApplications/TopoloAdmin/README.md
• PlatformApplications/TopoloAdmin/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-29

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