From 92df6281e8905a983ea547508f2965e9fabf170d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 23:57:50 +0000 Subject: [PATCH] Update docs/contributing/system-architecture.mdx Generated-By: mintlify-agent Mintlify-Source: dashboard-editor --- docs/contributing/system-architecture.mdx | 40 +++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/contributing/system-architecture.mdx b/docs/contributing/system-architecture.mdx index ee598582e..cc7d02971 100644 --- a/docs/contributing/system-architecture.mdx +++ b/docs/contributing/system-architecture.mdx @@ -696,6 +696,46 @@ flowchart TD | `PORT` | Server port | User | Optional (default: 6274) | | `DEBUG_MCP_SELECTION` | Enable debug logs | User | Optional | +### Hosted runtime config injection + +In hosted (web production) mode the server injects Convex URLs into the served `index.html` at request time so the client can connect to the correct Convex deployment without requiring a client rebuild. + +**How it works:** + +1. On startup the server reads `CONVEX_HTTP_URL` (the `*.convex.site` actions URL). +2. `getInspectorClientRuntimeConfig()` (`server/env.ts`) derives both URLs: + - `convexUrl` — the `*.convex.cloud` backend URL (hostname suffix swapped from `.convex.site` → `.convex.cloud`) + - `convexSiteUrl` — the normalized `*.convex.site` origin +3. `getInspectorClientRuntimeConfigScript()` serializes the config as a ` + Server->>HTML: Inject script into + HTML-->>Client: Served with runtime config + Client->>Client: getRuntimeConvexUrl() reads window.__MCP_RUNTIME_CONFIG__ + Client->>Client: Prefer runtime URL over VITE_CONVEX_URL +``` + +**Key files:** + +- `server/env.ts` — `getInspectorClientRuntimeConfig`, `getInspectorClientRuntimeConfigScript` +- `server/app.ts` — injects the script when serving `index.html` (Hono path) +- `server/index.ts` — injects the script when serving `index.html` (standalone path) +- `client/src/lib/runtime-config.ts` — `getRuntimeConvexUrl`, `getRuntimeConvexSiteUrl` +- `client/src/lib/convex-site-url.ts` — prefers runtime site URL over build-time env vars + ## Build & Deployment ### Build Process Flow