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_sequenceis 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.