Documentation Portal

Deploy the bridge with the current managed-environment contract.

This route condenses the validated managed deployment path: provision dependencies, expose one HTTPS bridge, apply migrations, bootstrap the first workspace, and verify health before runtime smoke.

Documentation map

The docs portal stays in the same application as the product shell so setup, deployment, connector, and developer guidance can evolve with the codebase.

In-repo docs7 foundation routes5 developer routesCurrent: Deployment

Foundation docs

  • OverviewRoute

    Start with the current architecture, product surfaces, and the stable documentation sections.

  • Getting StartedRoute

    Install the workspace, configure local env files, and run the first verification flow.

  • DeploymentOpen

    Use the managed bridge deployment order, health checks, migrations, and workspace bootstrap flow.

  • ConnectorsRoute

    Understand the Figma reference connector, Satellite runtime, and explicit session routing model.

  • SecurityRoute

    Review auth lanes, workspace isolation, policy controls, rate limiting, and audit semantics.

  • API ReferenceRoute

    Browse the stable HTTP route groups, shared envelopes, auth lanes, and machine-readable errors.

  • TroubleshootingRoute

    Use the current operational failure patterns for readiness, auth, session liveness, policy, and MCP issues.

Developer docs

  • DevelopersRoute

    Developer-facing entry point for HTTP, MCP, connector, and shared-contract guidance.

  • Developer QuickstartRoute

    Bring up the bridge, connect one runtime, and make the first explicit authenticated calls.

  • HTTP GuideRoute

    Use the bridge HTTP transport with the correct auth lane, shared envelopes, and explicit targetSessionId routing.

  • MCP GuideRoute

    Use the Streamable HTTP MCP endpoint, LIST_CAPABILITIES, and the same connector-neutral tool catalog.

  • Connector ModelRoute

    Understand connector definitions, capability metadata, data scopes, and high-risk policy presets.

Reference hostname topology

The current managed SaaS reference topology keeps the public web app, bridge, and Supabase on separate hosts so the apex domain belongs to the web surface only.

Vercel web surface: https://draftlinkapp.com and https://www.draftlinkapp.com

Render bridge surface: https://bridge.draftlinkapp.com

Supabase custom domain: https://supabase.draftlinkapp.com

The web app should reach the bridge and Supabase only through BRIDGE_SERVER_URL and NEXT_PUBLIC_SUPABASE_URL, keeping provider choice out of shared contracts and bridge orchestration.

Managed deployment order

The current deployment guide stays intentionally narrow so the first external Figma proof and later secure runtime follow-through share one repeatable path.

  1. Provision managed Postgres or Supabase-compatible Postgres.
  2. Provision managed Redis.
  3. Wire the managed hostname and callback topology first: apex web host on Vercel, bridge subdomain on Render, and Supabase custom subdomain.
  4. Build and publish the bridge image from the repository root.
  5. Create the bridge service, attach the image, and configure the full env contract, including the final bridge and Supabase hosts consumed by apps/web.
  6. Confirm /healthz and /readyz before routing traffic.
  7. Apply migrations, bootstrap the first workspace and API key, then connect the first runtime.

Deployment contract

These values are the current stable contract for the deployed bridge service.

RUNTIME_AUTH_TOKENSUPABASE_DB_URLSUPABASE_SERVICE_KEYREDIS_URLPORTSOCKET_CORS_ORIGINSUPABASE_URLRUNTIME_AUTH_MODE

The recommended first external proof still starts with RUNTIME_AUTH_MODE=runtime_token, POLICY_DEFAULT_EFFECT=allow, and RATE_LIMIT_MAX_REQUESTS_PER_MINUTE=60.

In the reference managed setup, apps/web should use BRIDGE_SERVER_URL=https://bridge.draftlinkapp.com and NEXT_PUBLIC_SUPABASE_URL=https://supabase.draftlinkapp.com.

Post-deploy bootstrap

Migrations and the first workspace bootstrap are part of the deployment, not optional follow-up.

Before or during the hostname cutover, run npm run validate:managed-topology to validate the paired web and bridge host contract in one operator handoff step.

Run npm run handoff:managed-cutover --workspace @uab/bridge-server -- --skip-smoke when you want one topology-only operator pass that records the result in the same report format used by the full cutover flow.

If you need to isolate one side only, run npm run validate:managed-saas-topology --workspace @uab/web so the web app points at the expected managed bridge and Supabase hosts.

Run npm run validate:managed-deployment-topology --workspace @uab/bridge-server so the bridge confirms SUPABASE_URL=https://supabase.draftlinkapp.com and the final SOCKET_CORS_ORIGIN policy before traffic reaches the public host.

For the first managed proof, SOCKET_CORS_ORIGIN=* is acceptable. After that, tighten it to a comma-separated HTTPS allowlist that includes https://draftlinkapp.com and any direct browser runtime origins such as the Figma host.

After the public runtime reconnects, rerun npm run handoff:managed-cutover --workspace @uab/bridge-server -- --bridge-url "https://bridge.draftlinkapp.com" --workspace-id "<workspace-id>" --session-id "figma-session-1" --api-key "<plaintext-api-key>" to chain topology validation with the authenticated external smoke.

Run npm run migrate --workspace @uab/bridge-server to apply the checked-in migrations in lexicographic order.

Run npm run bootstrap:first-workspace --workspace @uab/bridge-server to create the first workspace row, API key hash, and operator-visible runtime token values.

Retain the plaintext API key outside the database immediately, set the printed runtime token as RUNTIME_AUTH_TOKEN, and restart or redeploy the bridge after secret changes.