Skip to content

API edge and gateway roles

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Filled 2026-10-09

This page (platform-foundations/api-gateway-strategy.md) was empty. It now records the gateway roles the Factory needs, derived from the 2026-10-08 packet (GW-01…GW-07, re-validated) and the Oct-2026 target. A gateway is a responsibility with a caller, an audience, a trust boundary and a failure contract; it is not one microservice per platform folder.

Gateway roles

Role Responsibility and trust boundary Audience Existing reuse Initial placement
GW-01 Edge ingress TLS, host/path routing, external rate limits, origin policy, public exposure Internet clients Hosting ingress; Extensions.WebSecurity, Extensions.RateLimiting Selected in a deployment profile; no Factory reverse proxy exists
GW-02 Studio BFF / composition Client-shaped queries, authorized downstream composition, command forwarding, live projections; owns no business state Console, IDE extensions ConnectSoft.ApiGatewayTemplate (MVC BFF, explicitly not YARP), ApiCompositionOrchestration, Extensions.ResourceServer, Net.Http Cohosted with the Control plane API first; extracted for client, trust or scaling need
GW-03 Platform APIs Domain commands and queries with resource authorization, versioning, consistent errors Console, CLI, SDKs, CI MicroserviceTemplate / BaseTemplate, Extensions.ServiceModel, identity and tenant libraries One modular Control plane API; later per-service APIs
GW-04 AI model gateway Logical profiles, capability and privacy policy, route and fallback plan, budgets, provider credentials, invocation and usage receipts Runtime workers; later non-.NET consumers Extensions.AI, AI.AgentsFramework, RateLimiting, metering primitives In-process pipeline in the worker; optional host later (Model & Compute)
GW-05 Tool / MCP gateway Governed discovery and invocation: scope, side-effect policy, approval binding, idempotency, receipts; all MCP, in-process, REST and queue tool paths converge Agents Extensions.ModelContextProtocol (governance opt-in) plus a common executor (to build) Worker executor; separate boundary before untrusted code or shell (Capability & Tools)
GW-06 Integration / webhook ingress Signature verification, connection scope, replay protection, deduplication, connector dispatch External systems WorkerTemplate, vendor clients, messaging Limited endpoints per connector, only for required inbound scenarios
GW-07 Generated-product gateway Product-specific public ingress and optional BFF with its own audience and tenant semantics Product users ApiGatewayTemplate for BFF; chosen ingress for proxy Generated recipe; never the Factory's administration surface

Internal service discovery, gRPC/HTTP clients and a possible mesh are transport infrastructure; they neither replace per-service authorization nor create another gateway owner.

Trust rules (inherited and added)

  • Canonical ADR-0101: the gateway validates platform access tokens and route policy; it rejects, ignores or overwrites untrusted public tenant headers; backends still enforce domain and tenant authorization. Canonical ADR-0100: X-Tenant-Id is untrusted until validated at the gateway.
  • Downstream bearer forwarding in the BFF template is not a provider-secret broker or an MCP credential policy; provider and tool credentials flow through connections and the secret broker (Capability & Tools).
  • Streaming (model output, live run projections): cancellation propagation, partial-output status, backpressure; if reconnect is unsupported, say so and let the client query run state.

Current implementation

  • ConnectSoft.ApiGatewayTemplate is an MVC composition host with shared identity, rate limiting, downstream HTTP and observability; its README's "BaseTemplate reference-only" statement is drift, since its ApplicationModel inherits the BaseTemplate registration. DerechHaLev runs a custom BFF from it (not YARP).
  • No Factory edge, BFF, model gateway, tool gateway or webhook ingress exists.