Topolo Nexus
Gateway and usage-management layer for standardized AI, email, payment, generic application usage events, social-provider app credential and connection inventory, org-scoped model-preference access, and platform model lifecycle monitoring across Topolo.
Documentation Map
What It Is
Gateway and usage-management layer for standardized AI, email, payment, generic application usage events, social-provider app credential and connection inventory, org-scoped model-preference access, and platform model lifecycle monitoring across Topolo.
Architecture
Owners: ai-platform
Source repos: services/TopoloNexus
Dependencies: topolo-auth, applications-packages
Repo shape
No repo surface entries were detected from the registered repo paths.
Runtime Surfaces
Hosts:
https://nexus.topolo.app https://nexus-api.topolo.app https://nexus.stg.topolo.us https://nexus-api.stg.topolo.us No wrangler surface was discovered under the registered repo paths.
API Reference
Coverage: curated
Source: Topolo-io/topolo-platform/services/TopoloNexus/package.json
Source exists in repo: no
Canonical docs and gateway routes define Nexus as the typed provider gateway for AI, email, payments, YouTube Data API quota-unit metering, generic platform usage-event ingestion through `/platform/usage/events`, provider-credential resolution, reusable outbound sender identities, org-scoped model preferences, platform model lifecycle monitoring, and owner/super-admin scoped hard-limit option metadata, with platform-default credential mutation restricted to Auth `platform_super_admin` principals in the `admin` organization and backend service access handled by Auth-issued service JWTs rather than Nexus-local static service-client rows. Generic platform usage is queue-backed in production and staging through `USAGE_INGEST_QUEUE`, deduped by organization/request id, written to bounded raw `usage_logs`, aggregated into `usage_daily`, and emitted to Analytics Engine for scalable per-request telemetry. Nexus email sender-domain inventory includes `cloudflare_email` connections and Topolo-owned platform sender domains so Notify can deliver default transactional email without requiring each customer organization to register `topolo.app` or `stg.topolo.us`. `GET /api/models/governance` exposes platform defaults, org or platform-scoped overrides, recent usage by model, lifecycle/deprecation status, unpriced configured models, upstream candidate models, and catalog source health; `POST /api/models/sync` is platform-super-admin only and refreshes provider API/open catalog observations. Scoped spend now includes a platform scope (`scope_type = 'platform', scope_value = 'platform'`) for spend preflight and enforcement across all provider families so a global platform budget can cap AI and platform infrastructure spend (for example, Cloudflare, Stripe, email metering routes, and generic app request metering) while still honoring org/app-level controls. Service-context auth uses Auth-issued service JWTs with organization, app, and optional delegated user attribution headers; `usage:write` is required for generic usage ingestion. TopoloNotify and TopoloLocalize use `@topolo-io/worker-runtime` request usage monitoring so their API consumption is visible in Nexus separately from provider-specific email or translation usage. TopoloMail uses Auth service-JWT context for `/api/ai/completions` and `/api/ai/transcriptions`, with dynamic organization attribution and user delegation so mailbox AI and dictation usage are logged to the active user, organization, and app. TopoloWeb now forwards studio bearer tokens to Nexus for structured chat planning responses that are applied locally as typed site mutations, keeping Nexus responsible for provider invocation while TopoloWeb keeps blueprint validation and persistence. Supported AI routes can now also flow through authenticated Cloudflare AI Gateway from inside Nexus without changing the external `/api/ai/*` contract, with gateway transport settings kept in worker config and secrets rather than `provider_credentials` rows. The image preference surface now treats the Nexus org setting as the baseline while allowing products to request per-run inline overrides against the allowed model catalog, including OpenAI GPT Image models, without mutating the stored org preference, and raw provider HTTP 429 image-generation responses are retryable so requests continue through the configured AI fallback chain. Stripe price creation accepts either an existing product ID or caller-supplied product data while keeping provider credentials inside Nexus, and the typed payment surface now also supports subscription quantity updates plus invoice previews for owner-managed billing flows such as TopoloOne org seats. For TopoloP2P, Nexus remains behind TopoloPay only: P2P submits settlement requests to Pay, and Pay uses the Nexus typed payment surface for provider invocation. The gateway now also exposes authenticated `GET /api/widget` for TopoloOne live workspace. The dashboard browser login handoff and one-time sso_code callback redemption delegate to the shared Topolo auth client, embedded password-login success completes through Nexus app navigation after token persistence, and the authenticated dashboard workspace renders through the shared `TopoloAppShell` so account, launcher, command, theme, sidebar-collapse, and BugFix chrome stay package-owned. Staging dashboard builds inject staging Auth, Admin, dashboard, and gateway URLs, and the staging gateway is cataloged on `https://nexus-api.stg.topolo.us` with workers.dev only as a fallback route. Auth API-key scopes for the `topolo-nexus` service slug are manifest-aligned with the Nexus permission contract and synced to production D1.
App API page: /reference/apps/topolo-nexus
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:
srv_1bsTtzYkuSG4 API key scopes
Invoke Nexus AI-provider routes through authenticated service-client contexts
Resource pattern: none
View Nexus application and attribution metadata
Resource pattern: none
Manage Nexus spend and usage limits
Resource pattern: none
Manage Nexus organization-scoped administrative settings
Resource pattern: none
Provision organization-scoped Nexus service-client access
Resource pattern: none
Manage Nexus provider credentials and platform defaults
Resource pattern: none
Invoke Nexus service-client routes through authenticated service-client contexts
Resource pattern: none
View Nexus usage, budget, and provider telemetry
Resource pattern: none
Service permissions
ai:invoke, apps:read, limits:manage, org:admin, organizations:provision, provider_credentials:manage, service:invoke, usage:read
Data Ownership
No storage bindings were derived from wrangler configuration.
Queues / Cron / Workflows
Queue bindings:
No queue bindings were detected.
Cron triggers
No cron triggers were detected.
Workflow signals
No explicit queue/workflow script or cron signal was discovered.
Environment Variables and Bindings
Environment variables:
No environment variables were derived from wrangler configuration.
All wrangler bindings
No bindings were derived from wrangler configuration.
Deployments
Deployment environments: default only or not declared
Routes: workers.dev fallback or no explicit route declared
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: Topolo-io/topolo-platform/services/TopoloNexus/package.json
- Neither OpenAPI nor README-derived interface detail was found.
Debugging Runbooks
Start with these entrypoints:
- Topolo-io/topolo-platform/services/TopoloNexus/package.json
Change Log / Verification
Lifecycle: active
Last verified: 2026-06-04
Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.