{
  "generated_at": "2026-06-12T22:05:57.135Z",
  "system": {
    "id": "topolo-nexus",
    "name": "Topolo Nexus",
    "slug": "topolo-nexus",
    "kind": "application",
    "summary": "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.",
    "aliases": [],
    "lifecycle": "active",
    "last_verified": "2026-06-04",
    "owners": [
      "ai-platform"
    ],
    "repo_paths": [
      "services/TopoloNexus"
    ],
    "external_repo_paths": [],
    "service_ids": [
      "srv_1bsTtzYkuSG4"
    ],
    "visibility": "public",
    "api_contract": {
      "type": "curated",
      "source": "Topolo-io/topolo-platform/services/TopoloNexus/package.json",
      "notes": "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."
    },
    "primary_hosts": [
      "https://nexus.topolo.app",
      "https://nexus-api.topolo.app",
      "https://nexus.stg.topolo.us",
      "https://nexus-api.stg.topolo.us"
    ],
    "doc_paths": [
      "applications/nexus",
      "internal/apps/nexus"
    ],
    "security_assurance": {
      "risk_tier": "critical",
      "auth_boundary": "Topolo Auth caller context plus Nexus-owned provider gateway and credential authorization; embedded dashboard password-login success is completed by Nexus app navigation after shared Auth token persistence; bearer-token gateway calls require Auth /validate and fail closed when Auth validation is unavailable.",
      "tenant_isolation": "mixed",
      "external_inputs": [
        "browser",
        "api",
        "callback",
        "ai_agent_action"
      ],
      "sensitive_data": [
        "identity",
        "org_data",
        "provider_credentials",
        "customer_content",
        "telemetry"
      ],
      "last_security_review": "2026-04-30",
      "security_review_status": "reviewed",
      "pentest_status": "passed",
      "evidence_doc": "internal/apps/nexus"
    },
    "data_privacy": {
      "classification": "secret",
      "sensitive_data_classes": [
        "customer_content",
        "identity",
        "organization",
        "provider_credentials",
        "telemetry"
      ],
      "storage_locations": [
        "analytics_engine",
        "d1",
        "external_provider",
        "kv",
        "queue"
      ],
      "encryption_at_rest": "application_layer",
      "encryption_in_transit": "https_only",
      "key_management": "nexus_managed",
      "retention_policy": "partial",
      "deletion_export_status": "planned",
      "logging_redaction_status": "needs_review",
      "privacy_review_status": "reviewed",
      "enterprise_ready": false,
      "evidence_doc": "internal/apps/nexus"
    },
    "dependencies": [
      "topolo-auth",
      "applications-packages"
    ],
    "bugfix_policy": {
      "tier": "autonomous",
      "preferred_agent": "either",
      "require_validator": false
    },
    "public_hub_url": "/systems/topolo-nexus",
    "internal_hub_url": null,
    "application_api_url": "/reference/apps/topolo-nexus",
    "generated_openapi_url": null,
    "machine_urls": {
      "system": "/machine/systems/topolo-nexus.json",
      "application": "/machine/applications/topolo-nexus.json"
    }
  },
  "docs": {
    "public": [
      {
        "id": "applications/bugfix",
        "title": "Topolo BugFix",
        "summary": "Public overview of BugFix, including AI-assisted bug analysis, fix generation, and Nexus-backed provider usage.",
        "audience": "public",
        "tags": [
          "bugs",
          "ai",
          "automation",
          "github"
        ],
        "url": "/applications/bugfix",
        "last_verified": "2026-04-30"
      },
      {
        "id": "applications/commerce",
        "title": "TopoloCommerce",
        "summary": "Public overview of the multi-vertical commerce platform for venue operations, guest runtimes, and staff execution.",
        "audience": "public",
        "tags": [
          "commerce",
          "venues",
          "kiosk"
        ],
        "url": "/applications/commerce",
        "last_verified": "2026-05-13"
      },
      {
        "id": "applications/compose",
        "title": "TopoloCompose",
        "summary": "AI-native document generation, revision, styling, and export for formal documents in Topolo.",
        "audience": "public",
        "tags": [
          "compose",
          "documents",
          "ai",
          "application"
        ],
        "url": "/applications/compose",
        "last_verified": "2026-05-13"
      },
      {
        "id": "applications/nexus",
        "title": "Topolo Nexus",
        "summary": "Public overview of Nexus as the platform gateway for metered provider and application usage across Topolo applications.",
        "audience": "public",
        "tags": [
          "ai",
          "gateway",
          "usage",
          "platform"
        ],
        "url": "/applications/nexus",
        "last_verified": "2026-06-04"
      },
      {
        "id": "applications/one",
        "title": "TopoloOne",
        "summary": "Public overview of the TopoloOne dashboard, worker-backed growth surfaces, and the public developer-acquisition funnel.",
        "audience": "public",
        "tags": [
          "dashboard",
          "operators",
          "api-keys"
        ],
        "url": "/applications/one",
        "last_verified": "2026-05-14"
      },
      {
        "id": "applications/pay",
        "title": "Topolo Pay",
        "summary": "Public overview of the payment worker that handles orders, refunds, and payment operations.",
        "audience": "public",
        "tags": [
          "payments",
          "orders",
          "worker"
        ],
        "url": "/applications/pay",
        "last_verified": "2026-05-14"
      },
      {
        "id": "applications/roadmapper",
        "title": "Topolo Roadmapper",
        "summary": "Public overview of Roadmapper, including AI-assisted project onboarding, durable planning sessions, and stakeholder presentation delivery.",
        "audience": "public",
        "tags": [
          "roadmaps",
          "projects",
          "planning",
          "ai"
        ],
        "url": "/applications/roadmapper",
        "last_verified": "2026-05-13"
      },
      {
        "id": "applications/social-studio",
        "title": "Topolo Social Studio",
        "summary": "Public overview of the hybrid desktop and Cloudflare runtime used for AI-assisted social content planning and generation.",
        "audience": "public",
        "tags": [
          "desktop",
          "social",
          "generation",
          "creative"
        ],
        "url": "/applications/social-studio",
        "last_verified": "2026-05-13"
      },
      {
        "id": "applications/socialize",
        "title": "Socialize",
        "summary": "Public overview of the social publishing platform, brand-scoped resource bindings, and content operations.",
        "audience": "public",
        "tags": [
          "social",
          "publishing",
          "brands"
        ],
        "url": "/applications/socialize",
        "last_verified": "2026-05-13"
      }
    ],
    "internal": [],
    "runbooks": []
  },
  "authority": {
    "owners": [
      "ai-platform"
    ],
    "repo_paths": [
      "services/TopoloNexus"
    ],
    "service_ids": [
      "srv_1bsTtzYkuSG4"
    ],
    "dependencies": [
      "topolo-auth",
      "applications-packages"
    ],
    "aliases": []
  },
  "interfaces": {
    "contract_type": "curated",
    "contract_source": "Topolo-io/topolo-platform/services/TopoloNexus/package.json",
    "contract_source_exists": false,
    "openapi": null,
    "readme": null
  },
  "auth": {
    "depends_on_topolo_auth": true,
    "api_key_scopes": [
      {
        "id": "aks_nexus_ai_invoke",
        "name": "ai.invoke",
        "description": "Invoke Nexus AI-provider routes through authenticated service-client contexts",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "id": "aks_nexus_apps_read",
        "name": "apps.read",
        "description": "View Nexus application and attribution metadata",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "id": "aks_nexus_limits_manage",
        "name": "limits.manage",
        "description": "Manage Nexus spend and usage limits",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "id": "aks_nexus_org_admin",
        "name": "org.admin",
        "description": "Manage Nexus organization-scoped administrative settings",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "id": "aks_nexus_organizations_provision",
        "name": "organizations.provision",
        "description": "Provision organization-scoped Nexus service-client access",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "id": "aks_nexus_provider_credentials_manage",
        "name": "provider_credentials.manage",
        "description": "Manage Nexus provider credentials and platform defaults",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "id": "aks_nexus_service_invoke",
        "name": "service.invoke",
        "description": "Invoke Nexus service-client routes through authenticated service-client contexts",
        "resourcePattern": null,
        "kind": "api_key_scope"
      },
      {
        "id": "aks_nexus_usage_read",
        "name": "usage.read",
        "description": "View Nexus usage, budget, and provider telemetry",
        "resourcePattern": null,
        "kind": "api_key_scope"
      }
    ],
    "service_permissions": [
      {
        "id": "perm_nexus_ai_invoke",
        "name": "ai:invoke",
        "description": "Invoke Nexus AI-provider routes through authenticated service-client contexts",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "id": "perm_nexus_apps_read",
        "name": "apps:read",
        "description": "View Nexus application and attribution metadata",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "id": "perm_nexus_limits_manage",
        "name": "limits:manage",
        "description": "Manage Nexus spend and usage limits",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "id": "perm_nexus_org_admin",
        "name": "org:admin",
        "description": "Manage Nexus organization-scoped administrative settings",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "id": "perm_nexus_organizations_provision",
        "name": "organizations:provision",
        "description": "Provision organization-scoped Nexus service-client access",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "id": "perm_nexus_provider_credentials_manage",
        "name": "provider_credentials:manage",
        "description": "Manage Nexus provider credentials and platform defaults",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "id": "perm_nexus_service_invoke",
        "name": "service:invoke",
        "description": "Invoke Nexus service-client routes through authenticated service-client contexts",
        "resourcePattern": null,
        "kind": "permission"
      },
      {
        "id": "perm_nexus_usage_read",
        "name": "usage:read",
        "description": "View Nexus usage, budget, and provider telemetry",
        "resourcePattern": null,
        "kind": "permission"
      }
    ]
  },
  "runtime": {
    "primary_hosts": [
      "https://nexus.topolo.app",
      "https://nexus-api.topolo.app",
      "https://nexus.stg.topolo.us",
      "https://nexus-api.stg.topolo.us"
    ],
    "repo_entries": [],
    "wrangler_surfaces": [],
    "packages": []
  },
  "data": {
    "env_vars": [],
    "bindings": [],
    "queue_bindings": [],
    "storage_kinds": [],
    "workflow_signals": []
  },
  "deployment": {
    "commands": [],
    "routes": [],
    "environments": [],
    "assets_directories": [],
    "observability_enabled": false
  },
  "debugging": {
    "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."
    ],
    "entrypoints": [
      "Topolo-io/topolo-platform/services/TopoloNexus/package.json"
    ]
  }
}