Topolo Platform

Documentation Map

• Application hub
• Machine system JSON
• platform/architecture
• platform/api-keys

What It Is

Shared platform concepts spanning multi-context identity, zero-to-many org and household memberships, entitlements, owner-scoped billing boundaries, API keys, service registration, deployment, and observability.

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

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

API Reference

Coverage: curated

Source: PlatformApplications/TopoloDocs/src/content/public/platform

Source exists in repo: yes

Canonical platform behavior is documented directly in the docs monorepo, including the separation between Topolo identity, personal plus household context, organization membership, service entitlement, launcher eligibility, owner-scoped billing, and docs validation of Auth service catalog coverage.

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:

No Auth service ID mapped in docs yet.

API key scopes

No API key scopes were found in the checked-in Auth catalog for this system.

Service permissions

No role/permission catalog rows were found in the checked-in Auth permissions seed.

Data Ownership

Deployments

Deployment environments: production, preview, staging

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

Observability enabled: yes

Wrangler surfaces

• PlatformApplications/TopoloAuth/wrangler.toml -> topolo-auth-staging
• PlatformApplications/TopoloOne/apps/ai-chat-rag/wrangler.toml -> ai-chat-rag (assets ./public) (build pnpm --filter @topolo/ai-chat-rag build)
• PlatformApplications/TopoloOne/apps/dashboard-web/wrangler.toml -> topoloone
• PlatformApplications/TopoloOne/apps/dashboard-worker/wrangler.toml -> topoloone-worker (assets ./public) (build pnpm run build)
• PlatformApplications/TopoloOne/apps/marketing-site/wrangler.toml -> topoloone-website (assets out)

Build and deploy commands

• build — PlatformApplications/TopoloAuth/package.json :: wrangler deploy --dry-run --outdir .wrangler/build
• deploy — PlatformApplications/TopoloAuth/package.json :: wrangler deploy
• deploy:staging — PlatformApplications/TopoloAuth/package.json :: wrangler deploy
• deploy:production — PlatformApplications/TopoloAuth/package.json :: wrangler deploy --env production
• deploy:dry-run — PlatformApplications/TopoloAuth/package.json :: wrangler deploy --dry-run --outdir .wrangler/build
• build — PlatformApplications/TopoloAuth/packages/topolo-auth-client/package.json :: tsup src/index.ts --format esm,cjs --dts
• build — PlatformApplications/TopoloOne/apps/ai-chat-rag/package.json :: esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --platform=browser --target=es2022
• deploy — PlatformApplications/TopoloOne/apps/ai-chat-rag/package.json :: wrangler deploy
• deploy:dry-run — PlatformApplications/TopoloOne/apps/ai-chat-rag/package.json :: wrangler deploy --dry-run --outdir .wrangler/build
• build — PlatformApplications/TopoloOne/apps/dashboard-web/package.json :: tsc && vite build --mode production
• build:staging — PlatformApplications/TopoloOne/apps/dashboard-web/package.json :: env VITE_PUBLIC_URL=https://topoloone-dashboard-staging.pages.dev VITE_API_URL=https://one.stg.topolo.us VITE_AUTH_URL=https://auth.stg.topolo.us VITE_TOPOLO_AUTH_URL=https://auth.stg.topolo.us VITE_STORE_API_BASE_URL=https://developers.stg.topolo.us/api/store VITE_P2P_API_URL=https://p2p.stg.topolo.us sh -c 'tsc && vite build --mode production'
• preview — PlatformApplications/TopoloOne/apps/dashboard-web/package.json :: vite preview
• deploy:check — PlatformApplications/TopoloOne/apps/dashboard-web/package.json :: node ../../scripts/check-deploy-fresh.mjs
• deploy — PlatformApplications/TopoloOne/apps/dashboard-web/package.json :: node ../../scripts/check-deploy-fresh.mjs && rm -f node_modules/.cache/wrangler/pages.json node_modules/.cache/wrangler/wrangler-account.json && rm -rf dist && pnpm run build && CLOUDFLARE_ACCOUNT_ID=49ef1ba682ad8cfd720c86699ae17521 wrangler pages deploy dist --project-name topoloone --branch main --commit-dirty=true
• deploy:staging — PlatformApplications/TopoloOne/apps/dashboard-web/package.json :: rm -f node_modules/.cache/wrangler/pages.json node_modules/.cache/wrangler/wrangler-account.json && rm -rf dist && pnpm run build:staging && CLOUDFLARE_ACCOUNT_ID=4f4e1c69a3830946f9fea7b1eb7531ac wrangler pages deploy dist --project-name topoloone-dashboard-staging --branch staging --commit-dirty=true
• build — PlatformApplications/TopoloOne/apps/dashboard-worker/package.json :: esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --platform=browser --target=es2022

Failure Modes

• No Auth service ID is registered for this system.

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloAuth/wrangler.toml
• PlatformApplications/TopoloOne/apps/ai-chat-rag/wrangler.toml
• PlatformApplications/TopoloOne/apps/dashboard-web/wrangler.toml
• PlatformApplications/TopoloOne/apps/dashboard-worker/wrangler.toml
• PlatformApplications/TopoloOne/apps/marketing-site/wrangler.toml
• PlatformApplications/TopoloDocs/src/content/public/platform
• PlatformApplications/TopoloAuth/README.md
• PlatformApplications/TopoloAuth/package.json
• PlatformApplications/TopoloAuth/packages/topolo-auth-client/package.json
• PlatformApplications/TopoloOne/apps/ai-chat-rag/package.json
• PlatformApplications/TopoloOne/apps/dashboard-web/package.json
• PlatformApplications/TopoloOne/apps/dashboard-worker/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.