Skip to content

ScreamingFace architecture on PULSE

This page describes the deployed dev architecture and the ownership boundaries that make it safe to operate. For the exact revision and latest proof, start with the quick rundown and evidence and status.

Runtime path

flowchart LR
    C[Developer or service client]
    CF[Cloudflare Access]
    T[Dedicated cloudflared tunnel]
    E[Shared Envoy Gateway<br/>cf-protected tier]
    U[url4-cloud<br/>sf-fusion :9108]
    J[Ephemeral Runner Job]
    N[(NATS JetStream<br/>:4222)]
    A[aigateway<br/>sf-aigw :9105]
    D[(PostgreSQL<br/>:5432)]
    P[Model provider]

    C --> CF --> T --> E --> U
    U -->|create and watch| J
    U <--> N
    J <--> N
    J --> A
    A --> D
    A -->|HTTPS, server only| P

The public hostname terminates at a platform-owned route. /ws and REST traffic both reach url4-cloud, but the WebSocket rule has no request timeout while the REST catch-all has a 90-second timeout. aigateway has no public Ingress or Gateway route.

Namespace and ownership map

flowchart TB
    subgraph EDGE["sf-edge"]
        CT[cloudflared<br/>tenant workload]
        CTS[ServiceAccount, secret rail,<br/>network boundary<br/>platform owned]
    end

    subgraph FUSION["sf-fusion"]
        UC[url4-cloud and NATS<br/>tenant chart]
        RJ[Runner Jobs<br/>created by url4-cloud]
        FP[HTTPRoute, SecurityPolicy,<br/>Secret, RBAC, NetworkPolicy<br/>platform owned]
    end

    subgraph AIGW["sf-aigw"]
        AC[aigateway and migration Job<br/>tenant chart]
        AP[PostgreSQL, Secret rail,<br/>ServiceAccount, NetworkPolicy<br/>platform owned]
    end

    subgraph SCORE["sf-scoreboard"]
        SC[Reserved namespace<br/>default-deny scaffold]
    end

    CT --> FP --> UC
    UC --> RJ --> AC
    AC --> AP

The tenant chart owns product workloads and Services. The platform owns the trust boundary: namespaces, routes, identity policy, Secrets, storage, ServiceAccounts, RBAC, and network openings. This is the practical application of ADR-0006.

Namespace Running purpose Workload owner Boundary owner
sf-edge Dedicated Cloudflare tunnel ScreamingFace chart/configuration contract PULSE
sf-fusion Public url4-cloud, NATS, Runner Jobs, identity inspector ScreamingFace PULSE
sf-aigw Private aigateway and its migration hook ScreamingFace PULSE
sf-scoreboard Reserved, default-denied scaffold ScreamingFace when introduced PULSE

Namespace creation and cluster-scoped resources remain platform-owned. The ScreamingFace Argo project may deploy only approved namespaced kinds into its listed sf-* destinations. Gateway and cluster-scoped kinds are denied.

Identity and trust boundaries

Cloudflare Access authenticates the caller. Envoy verifies the Access assertion, removes client-supplied reserved identity headers, and injects the verified identity before forwarding. The route also overwrites X-Tenant with sf-fusion.

Interactive user traffic carries X-User-Email. Non-interactive Cloudflare service identity is represented separately at the edge and is not accepted by aigateway as a user identity. url4-cloud forwards the verified user identity and optional X-Profile to the Runner; the Runner forwards them to aigateway.

This makes network reachability part of aigateway authentication. A caller that can reach port 9105 could otherwise forge X-User-Email, so:

  • aigateway has no public route;
  • ingress is limited to url4-cloud, Runner Jobs, and the named status probe;
  • the application also checks that its direct peer belongs to the configured Pod network;
  • only the aigateway server pod can reach model providers.

State and availability

  • url4-cloud is intentionally one replica because subscriber readiness is held in an in-process registry. More replicas need affinity or a shared attach state before they are safe.
  • Runner Jobs are ephemeral. Their stdout is diagnostic output; the application result is delivered through JetStream.
  • NATS JetStream retains lifecycle events and supports replay. from_sequence is 1-based and inclusive.
  • PostgreSQL stores aigateway accounts, profiles, and encrypted provider credentials. The current dev database is a single-instance, disposable platform service; it is not a production availability design.
  • The old trial stack has been retired and is not a rollback target.

Source of truth