Architecture & request flow

GovBridge consists of two clearly separated building blocks that share exactly one database (Supabase, EU) and one encryption key.

This separation is deliberate: the bridge service knows no SovrGPT sessions, no chat content and no users — it only sees an endpoint slug, a token and a JSON-RPC call. That keeps the blast radius small.

Data flow at a glance

┌──────────┐   MCP (JSON-RPC)    ┌──────────────┐   CMIS (JSON/HTTP)  ┌────────────────┐
│ SovrGPT  │ ──────────────────▶ │  GovBridge   │ ─────────────────▶ │ LOB system     │
│  (EU)    │ ◀────────────────── │   (EU, RW4)  │ ◀───────────────── │ DMS (your org) │
└──────────┘   tool result       └──────────────┘   API response      └────────────────┘

All three stations sit in the EU. There is no hyperscaler in the data path and no caching of business content. With the FIT-Connect protocol the backend is the FITKO submission API instead of a DMS, and the payload additionally leaves the bridge end-to-end encrypted (JWE).

One tool call, step by step

1. SovrGPT decides in the chat to call a tool and sends POST https://govbridge.sovrgpt.com/<slug>/<protocol> with Authorization: Bearer <bridge-token> and a JSON-RPC 2.0 body.
2. Routing. The service parses the route (exactly two segments /<slug>/<protocol>), accepts only POST and checks whether <protocol> is in the instance allowlist (GOVBRIDGE_PROTOCOLS, e.g. cmis, fit-connect).
3. Two-factor resolution (see below). If it fails → a generic 401, without revealing which factor was missing.
4. Body limit. The JSON-RPC body is read with a hard 1 MB limit (single call or batch).
5. Dispatch. The MCP dispatcher handles initialize, tools/list, tools/call and ping. For tools/call the plugin matching the protocol is selected.
6. Real-time backend call. The plugin matching the protocol builds the backend auth header and calls the backend via fetch with a hard timeout: the CMIS plugin fetches or files documents and applies the size policy; the FIT-Connect plugin encrypts the submission end to end (JWE) and runs through announce → attachments → finalize. Both return MCP content parts.
7. Response & logging. The service logs metadata only (org/endpoint IDs, tool, duration, status) and answers with the JSON-RPC response (or 202 for pure notifications).

Two-factor tenant resolution

Every incoming call carries two independent factors, and both must point to the same endpoint row:

1. Slug (in the URL path, opaque) — identifies the endpoint.
2. Bearer token (in the Authorization header) — proves authorisation.

The procedure is constant-time and never reveals on failure which factor did not match:

1. No token → unauthorized.
2. Look up the endpoint by slug (only active, non-revoked rows).
3. Compare SHA-256(token) in constant time against the stored hash. Mismatch → unauthorized.
4. The URL <protocol> must match the stored protocol exactly (no cross-protocol reuse).
5. Backend credentials are decrypted transiently — only in RAM for the duration of this one call, never logged.

The plaintext token exists only once, at provisioning time; only its hash is stored — the same pattern as for API keys.

Statelessness

The dispatcher is stateless: every request carries its own resolved tenant context, there is no per-connection session object. Only two uncritical things are cached in process RAM, purely to save round trips:

• the OAuth backend token per endpoint (until shortly before it expires),
• the CMIS repository service document (5 minutes).

Business content is never cached.

Next

• Tools & interfaces — the cmis_* and fit_* tools.
• Security & compliance — crypto and GDPR.
• Operations — hosting, limits, error behaviour.