Przejdź do treści

Operator runbook — Connections UX (Plan 128)

Plan 128 replaced the brief Plan 119 split-routing experiment with a single connector entry-point: the inline vendor tile grid on /connections. There is no longer a separate /connections/new / /connections/new-legacy shell, and no connection_method_picker tenant flag.

What ships

  • /connections renders four sections of bigger vendor tiles (~200x140 desktop), grouped by category:
  • Cloud providers — Azure, AWS, Google Cloud
  • Identity providers — Microsoft 365, Google Workspace (coming soon)
  • Code platforms — GitHub
  • LLM vendors — OpenAI, Anthropic, Databricks
  • Each tile shows a monochrome vendor logo, name, one-line trust posture summary, and small mini-badges for the methods available from MethodAvailability.
  • Clicking a tile opens that vendor's dialog as a modal. Multi-method dialogs (AWS, GCP, Azure, GitHub) render tabs above the form; single-method dialogs (M365, OpenAI, Anthropic, Databricks) skip the tab UI.
  • Each (vendor × method) tab uses a 2-column layout: form fields on the left, step-by-step instructions on the right.

Disabled-tile semantics

Tiles render in three disabled states:

  • Operator-disabled — ProviderAvailability.available === false (the cp-api Container App is missing the OAuth client env vars). Tile renders at 60 % opacity, lock icon top-right, hover tooltip lists the missing env vars by name.
  • No active tenant — caller has no effective tenant (platform admin not impersonating). Same visual treatment plus a tooltip pointing at /admin/tenants.
  • Coming soon — frontend-only marker (today: Google Workspace). Renders a “Coming soon” pill instead of the lock.

Removed surfaces

The following are gone after Plan 128 and should be pruned from any operator runbook screenshots:

  • /connections/new (Plan 119 picker shell)
  • /connections/new-legacy (Plan 119 legacy fallback)
  • The "Add new connection" top-right button on /connections
  • tenants.settings.flags.connection_method_picker (writes via the admin flags UI are now rejected with a 422; pre-existing values in the JSONB block are harmlessly ignored by the reader)

Vendor logos

Logo assets live under apps/frontend/components/connection-logos/. All eight current vendors use the simpleicons.org CC0 SVGs, normalised to a 0 0 24 24 viewBox and fill="currentColor" so the tile theme switches with the rest of the dashboard. The VendorLogo React component renders one of the inlined paths per vendor key; unknown keys fall back to a lucide Globe icon so the tile doesn't blow up if the vendor catalog grows ahead of the component.

To add a new vendor logo:

  1. Drop the SVG file in apps/frontend/components/connection-logos/ with the source URL + license header.
  2. Add a matching LogoSpec entry to the LOGOS map in vendor-logo.tsx (the path data inlined, viewBox 0 0 24 24, fill="currentColor").
  3. Add the new vendor key to the page tile list with a matching VENDOR_SUMMARY + VENDOR_LABEL entry on connections/page.tsx.

Per-method instructions

Customer-facing walkthroughs live in apps/frontend/components/connection-instructions/, one component per (vendor × method) combo:

  • aws-assume-role.tsx — IAM role + trust policy walkthrough
  • aws-eventbridge.tsx — CloudFormation snippet + bus ARN flow
  • gcp-oauth-refresh.tsx — OAuth consent screen + scopes
  • gcp-wif.tsx — gcloud setup commands (mirrors docs/customer/gcp-wif-onboarding.md)
  • azure-oauth.tsx — corporate-domain caveat + admin consent
  • azure-federated-identity.tsx — no customer-side setup; points at /admin/setup
  • github-oauth.tsx — GitHub OAuth scopes + SSO note
  • github-webhook.tsx — App install + webhook secret rotation
  • m365-oauth.tsx — Microsoft Graph scopes + global-admin consent

When tweaking copy, edit the component directly — the docs page (in docs/customer/) stays the source-of-truth for the runbook prose, but the dialog component duplicates the gory snippets so a customer mid-flow doesn't have to leave the dialog.