Platform architecture¶

A Poly instance is a control-plane API, a gateway, a catalog, Knative FaaS for server functions, and a portal (Canopy / PolyUI). This page is the product runtime.

Managed instances today: NA1 (AWS us-west-2) and EU1 (AWS eu-west-1). The same product APIs can run on customer Kubernetes. Public self-host install docs are deferred; this page does not include cluster recipes or secrets.

Day-1 orientation: How Poly fits together. Picking a resource type: Choosing a Poly resource.

Components¶

Piece	Role
Control plane	Authenticated REST for catalog CRUD and execute metadata. Swagger on the instance: API reference
Gateway	HTTP front door: API Function outbound proxy; API Endpoint (webhook) ingress; injected `x-http-method` / `x-original-uri`
Catalog	Env-scoped resources (functions, Vari, endpoints, jobs, …). Namespaced by Context
FaaS (Knative)	Server Function revisions. Client functions never get their own revision
Portal	Canopy apps. PolyUI is the default management app (`/canopy/polyui/login`)
Generated SDK	Language bindings from a catalog snapshot (`npx poly generate` / `python -m polyapi generate`)

Every execute path checks the Bearer API key (tenant, environment, permissions) plus environment entity access. Authentication model. Visibility gates discovery, not writes. Visibility.

Request flows¶

Auth shape on every hop:

Bearer <api-key>  →  AuthData { tenant, environment, user|application, permissions, … }
                  →  execute path (api | server | trigger | job | graphql)

API Function (outbound)¶

Caller (SDK or REST)
  → POST /functions/api/:id/execute
  → Auth + environment access
  → Gateway applies the trained HTTP template
  → Third-party response returned to the caller

Server Function¶

Caller
  → POST /functions/server/:id/execute
  → Auth + access
  → Knative invoke
  → Body/status to the caller
Optional: serverSideAsync → HTTP 202 { executionId }

Client Function¶

Caller process (laptop, or inside a server function)
  → Client code runs in-process
  → No /functions/client/:id/execute route

Inbound API Endpoint (webhook) → Trigger¶

HTTP → Webhook Handle
  → Inject x-http-method, x-original-uri
  → Optional security server functions (boolean gate)
  → Fan-out:
       Triggers → server function (eventPayload, headersPayload, paramsPayload)
       Socket listeners → { body, headers, params, executionId }
  → If Wait for Response: HTTP body from that server function
  → Else: static responsePayload (or empty 200)

Only one trigger per webhook may wait for the response. Events and Triggers.

Job¶

Scheduler → job function entries
  → execute server function with configured
    eventPayload / headersPayload / paramsPayload

Job wait timeouts do not cancel the Knative run. Limits and timeouts.

GraphQL Subscription¶

Provider event → GraphQL service
  → server function args [event, params]
  → Also a socket subscription event to live listeners

AI Function¶

Caller → POST /functions/ai/:id/execute
  → Auth + access
  → LLM (optional tools = API or server functions)
  → Separate meter from server function executions

AI Functions.

Debugging which hop failed¶

Symptom	Hop to check
401 / 403	API key, environment, permissions
Train succeeded, execute 404	API Function host URL mode (Using OpenAPI Specs)
Webhook always returns stub JSON	No Wait for Response trigger
Job failed ~10 min; logs still going	Job wait vs server function `limitTime`
Empty webhook body	Content-Type (JSON/XML/text only)
Assumed Canopy Architecture explains FaaS	Wrong page; use this one