> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polycore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> The control plane, customer-hosted runner, trust boundaries, and request lifecycle.

Polycore separates governance from execution. The internet-facing control plane
decides whether and where an operation may run. A customer-hosted runner holds
the scoped authority for private systems and performs the operation inside your
environment. For supported shared SaaS resources, a separate private hosted
integration executor holds an encrypted provider grant and performs only a
typed, bounded operation through a fixed provider adapter.

That split is the central trust boundary:

<Columns cols={3}>
  <Card title="Polycore control plane" icon="cloud">
    Stores governance and product state: organizations, projects, environments,
    runner registrations, capability metadata, requests, approvals, audit
    records, and dashboard pages. It does not hold runner execution credentials
    or direct provider tokens.
  </Card>

  <Card title="Hosted integration executor" icon="lock-keyhole">
    A separate private service stores supported shared SaaS grants encrypted
    with KMS-backed envelope encryption. It has fixed provider hosts, typed
    operations, bounded results, least-privilege service IAM, and no public
    ingress.
  </Card>

  <Card title="Your infrastructure" icon="server-cog">
    Runs the Polycore runner with network access to your selected systems. The
    runner resolves execution credentials locally, exposes a reviewed capability
    catalog, and performs signed work dispatched by the control plane.
  </Card>
</Columns>

## System topology

```mermaid theme={"system"}
%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart LR
  subgraph callers["Callers"]
    Slack["Slack"]
    MCP["AI agents over MCP"]
    Web["Admin dashboards"]
  end

  subgraph cloud["Polycore cloud"]
    CP["Control plane"]
    Executor["Private integration executor"]
    Catalog[("Catalog and policy")]
    Audit[("Requests, approvals, audit")]
    CP --- Catalog
    CP --- Audit
    CP -- "Private typed RPC" --> Executor
  end

  subgraph customer["Your infrastructure"]
    Runner["Runner"]
    Secrets[("Secret manager or workload identity")]
    Data[("Databases and APIs")]
    Runner --> Secrets
    Runner --> Data
  end

  Slack --> CP
  MCP --> CP
  Web --> CP
  Runner == "Persistent outbound WebSocket" ==> CP
  CP -- "Signed dispatch" --> Runner
  Executor -- "Fixed-host provider API" --> Notion["Supported SaaS"]
```

<Note>
  "Outbound-only" describes the runner's control and execution path. A hosting
  platform can probe a credential-free health endpoint that accepts no
  dispatches; the GCP preset restricts it to Google Cloud health probes. The
  Polycore control plane remains public because Slack, browsers, MCP clients,
  and runners must reach it. The important boundaries are that the public
  control plane does not hold runner credentials or direct provider tokens, and
  the private executor is isolated from the public web and runner listener.
  Hosted integrations are limited to the providers and operations Polycore
  explicitly implements.
</Note>

## The four architectural roles

<Columns cols={2}>
  <Card title="1. Front doors" icon="panels-top-left">
    Slack, MCP clients, and admin dashboards initiate requests. They never
    receive the datastore credential. Each interface carries caller and project
    context into the same control-plane path.
  </Card>

  <Card title="2. Control plane" icon="shield">
    Authenticates the caller, resolves the project and environment, selects a
    connected runner, evaluates the capability hazard, creates approvals, and
    records the request lifecycle.
  </Card>

  <Card title="3. Hosted integration executor" icon="lock-keyhole">
    Runs typed, read-only provider adapters for project-wide shared SaaS
    connections. It decrypts credentials only inside the isolated executor and
    returns bounded results through the control plane gateway.
  </Card>

  <Card title="4. Runner" icon="server">
    Advertises the capabilities available for one project and environment,
    verifies signed dispatches, resolves local credentials, executes the
    selected capability, and returns a structured result.
  </Card>

  <Card title="5. Downstream systems" icon="database">
    Your database, API, or service enforces its own IAM and network boundary.
    Polycore adds a governed invocation path; it does not replace the downstream
    system's access controls.
  </Card>
</Columns>

## Request lifecycle

```mermaid theme={"system"}
sequenceDiagram
  autonumber
  participant C as Caller
  participant P as Polycore control plane
  participant H as Human approver
  participant R as Runner in your infrastructure
  participant E as Private integration executor
  participant D as Database or SaaS API

  C->>P: Request a typed capability
  P->>P: Authenticate, route, classify hazard
  alt Customer-hosted runner capability
    P->>R: Signed dispatch
    R->>R: Resolve local credential
    R->>D: Execute with scoped authority
  else Hosted direct integration
    P->>E: Authenticated typed RPC
    E->>E: Decrypt provider grant inside isolated service
    E->>D: Execute fixed-host read operation
  else Non-read runner capability
    P->>H: Approval decision
    H-->>P: Approve or deny
    P->>R: Signed dispatch after approval
    R->>R: Resolve local credential
    R->>D: Execute with scoped authority
  end
  D-->>R: Result
  D-->>E: Bounded provider result
  R-->>P: Structured response
  E-->>P: Bounded structured response
  P->>P: Record invocation and decision
  P-->>C: Return result
```

<Steps>
  <Step title="Identify and route">
    The control plane resolves the organization, project, caller, and requested
    capability. Runner capabilities resolve to an exact environment.
    Project-wide direct capabilities bypass environment routing and resolve to
    their bound hosted connection.
  </Step>

  <Step title="Apply the policy gate">
    Your access policy decides the path: invocations it clears may dispatch
    immediately, while invocations it holds require an approval record. Direct
    web actions from an authenticated owner or admin may record that decision
    inline, while other interfaces wait. Delegated code has `unknown` hazard and
    always remains pending for review.
  </Step>

  <Step title="Sign or invoke privately">
    Runner capabilities use a signed envelope over the runner's existing
    WebSocket. Hosted direct capabilities use an authenticated private RPC to
    the isolated executor. Neither path exposes the credential to the caller.
  </Step>

  <Step title="Verify and execute">
    The runner verifies the signature, validates the input schema, resolves only
    the secrets declared for the capability, and performs the operation.
  </Step>

  <Step title="Return and record">
    The result returns over the same connection. The control plane records the
    user-facing request, governed invocation, timing, outcome, and any approval
    decision.
  </Step>
</Steps>

## Runner connection and enrollment

The runner is a long-running outbound worker, not an inbound API server.

<Columns cols={3}>
  <Card title="Outbound network" icon="arrow-up-right">
    The runner opens and maintains a WebSocket to the control plane. Your
    firewall does not need to expose a public runner port.
  </Card>

  <Card title="Enrollment identity" icon="badge-check">
    Polycore provisions a runner id, join token, and signing secret for one
    project and environment. They authenticate enrollment and dispatches, not
    access to your downstream systems.
  </Card>

  <Card title="Self-healing connection" icon="refresh-cw">
    Heartbeats detect a dead connection. The runner reconnects with bounded
    backoff and advertises its current catalog again.
  </Card>
</Columns>

## Deployment topology

A runner belongs to exactly one Polycore project and one environment. Separate
production and staging runners keep credentials, network reach, and failure
domains isolated.

```mermaid theme={"system"}
flowchart LR
  CP["Polycore control plane"]

  subgraph dev["Your dev environment"]
    RD["Runner"]
    DD[("Dev systems")]
    RD --> DD
  end

  subgraph prod["Your production environment"]
    RP["Runner"]
    DP[("Production systems")]
    RP --> DP
  end

  RD == "Outbound" ==> CP
  RP == "Outbound" ==> CP
```

The control plane routes an invocation to the runner enrolled for the selected
environment. The runner does not accept an arbitrary environment argument and
switch credentials at runtime.

## What crosses the boundary

<AccordionGroup>
  <Accordion title="From the runner to the control plane" icon="arrow-left">
    Enrollment identity, project slug, capability names and JSON schemas, hazard
    metadata, optional agent context, connection health, structured results, and
    execution errors.
  </Accordion>

  <Accordion title="From the control plane to the runner" icon="arrow-right">
    Signed invocation envelopes containing the capability name and validated
    arguments, plus connection heartbeat messages.
  </Accordion>

  <Accordion title="What stays in your infrastructure" icon="lock-keyhole">
    Database passwords, service-account authority, API keys, local secret
    values, and direct network access to private systems.
  </Accordion>

  <Accordion title="What stays in the hosted executor" icon="key-round">
    Shared direct-integration grants remain encrypted in the private executor's
    secret store. The public control plane stores only safe grant metadata and
    an opaque credential id. Provider tokens never reach callers, prompts,
    schemas, audit records, or dashboard responses.
  </Accordion>
</AccordionGroup>

<Warning>
  Invocation inputs and returned results are part of the control-plane audit
  path. During integration, classify sensitive fields and design bounded,
  redacted outputs where needed. Keeping execution credentials local does not
  make every result non-sensitive.
</Warning>

## Continue reading

<Columns cols={3}>
  <Card title="The runner" icon="server" href="/concepts/runner">
    See how configuration, runtime identity, capabilities, and secrets fit
    together.
  </Card>

  <Card title="Security" icon="shield-check" href="/concepts/security">
    Review credential custody, least privilege, trust boundaries, and failure
    assumptions.
  </Card>

  <Card title="Capabilities" icon="blocks" href="/concepts/capabilities">
    Understand query and action kinds, hazard classes, and the catalog.
  </Card>
</Columns>