Deployment Options

Descriptor Release Contract

A release is not only a container image. The six environment descriptors — assembly.yaml, gateway.yaml, economics.yaml, secrets.yaml, bundles.yaml, and bundles.secrets.yaml — carry platform selection, admission policy, economics, app versions, surfaces, named-service registrations, UI sources, feature flags, and secret material or references.

Current public Helm-chart boundary: the maintained chart consumes four overlays directly: assembly.yaml, gateway.yaml, bundles.yaml, and secrets.yaml. It does not currently mount or seed economics.yaml or bundles.secrets.yaml. Operators using that path must provision those two authorities through their deployment-specific economics and app-secret workflow; do not assume the Helm invocation loaded all six families.

release.yaml is app release metadata, not runtime configuration. Runtime surfaces, interface declarations, config templates, storage docs, tests, and release metadata should remain synchronized. See Object Ecosystem & Ontologic Contracts for the provider/consumer contract this descriptor layer enables.

Storage Topology

Temporary integration staging is not a distributed object store. Upload and consuming operations must see the same storage root. Provider-owned mail and Slack bytes remain provider-owned until a requested download or materialization occurs.

Collaborative App Preload

Proc workers divide startup preload work with Redis claims keyed by the descriptor-resolved app generation. Claims are heartbeat-renewed; successful work writes a generation-specific done marker. Changing path, module, repo/ref/subdir, singleton flag, or commit produces a new generation.

UI builds are strongly owned process-local tasks and outlive an initiating HTTP request. Source and node_modules stay in worker-local temporary storage; shared storage holds the cross-worker lock, heartbeat, TTL, signature, temporary output, and atomically published artifact. npm/Vite runs in a dedicated process group that is terminated and reaped on timeout or explicit cancellation. Signature publication and lock release happen before expensive local cleanup, so another request or worker sees the completed artifact immediately.

Shared-filesystem locks are still the final guard around widget and main-view artifact writes, especially on EFS. They are not the main work-distribution mechanism. A worker crash stops its heartbeat and lock expiry permits retry. If Redis is unavailable, workers fall back to local traversal protected by those shared-storage locks. Health reports bundles_preload_skipped_claimed and bundles_preload_skipped_done.

Application-Hosted Sites and CDN

Website declarations live under the app's config.ui.main_view.site in bundles.yaml. Valid declarations compile into an immutable ApplicationSiteCatalog. Redis atomically distributes generation snapshots; each proc routes requests from a hot in-memory copy and rejects delayed generations. Redis is not read on every site request.

Direct aliases use /sites/{alias}. For a dedicated hostname, a CDN preserves the viewer host and rewrites clean paths to /api/integrations/site-root/{path}. The CDN forwards and caches responses; it does not own or query the catalog, and OpenResty contains no app/site list.

Monitoring & Observability

The platform exposes operational signals through a combination of log streams, Redis-backed queue metrics, and a health endpoint. These signals are intended for operators monitoring a deployed instance.

These records provide reviewable operational evidence. They are not automatically write-once, tamper-evident compliance records, and the deployment does not acquire a compliance attestation merely by enabling telemetry or a WAF.

Conversation Lanes and Scheduled Work

Conversation event order is defined by Redis lane sequence for one tenant/project/user/conversation/agent identity. Processor queues schedule bodyless lane wakes; they do not define event order. Monitor accepted versus processed lane cursors, wake backlog, active-consumer freshness, event-source owner leases, and background Data Bus/job-stream pending state in addition to aggregate queue depth.

Processor Health

Each processor instance reports liveness through its own container health check. In the private ECS topology, the ALB target group tracks web-proxy; internal chat-ingress and chat-proc use container checks plus ECS/Cloud Map orchestration rather than ALB target membership. Compose likewise uses service-specific container checks.

Log Streams

All platform services emit structured log output to stdout, captured by the container runtime. In ECS deployments logs flow to CloudWatch Logs; in Compose deployments they are available via docker compose logs. Log lines include request IDs, tenant/project scope, internal app id, and error classification where applicable.

Metrics Endpoint

The Operations REST API (served by chat-proc) exposes operational data to authorized callers. App-level turn, economics, and error data can be queried through the app and platform operation surfaces. Use structured container logs and the deployment's log backend for service-level diagnosis.

Connection Pooling

Redis and Postgres connection pools are created once per worker process during FastAPI lifespan startup and stored in app.state. Total connections scale with worker count.

Redis Pools

Pool size is controlled by GATEWAY_CONFIG_JSON.pools.<component>.redis_max_connections. If unset, the pool is unbounded and grows with load. Pub/sub and blocking calls consume connections from the pool, not on top of the cap.

Postgres Pool

Each worker creates one asyncpg pool. Size is controlled by pools.<component>.pg_pool_max_size and pg_pool_min_size. If not set, it defaults to service_capacity.<component>.concurrent_requests_per_process.

# Total connections per instance
pg_conns_per_instance = workers × pg_pool_max_size
redis_conns_per_instance = workers × pools_per_worker × redis_max_connections

Connection Lifecycle

Shared Redis clients set socket_connect_timeout=5, health_check_interval=30, socket_keepalive=True, and retry_on_timeout=True. A centralized Redis health monitor tracks PING health and emits up/down events. On reconnect, the service automatically rebuilds SSE relay subscriptions and reconnects gateway config pub/sub listeners.