CareerVector — Cloud Infra & Vendor Reference

Canonical reference for which cloud vendor runs what, why, and the hard rules that keep the architecture sustainable.

Status: live spec. If reality and this doc disagree, fix one or the other immediately. Last updated: 2026-04-28.

The headline rule

FREE TIER ONLY. ALWAYS. Across every vendor, on every service.

This is not a budget constraint — it is an architectural discipline:

• Cloud bills kill startups silently. Many shipped products bleed cash on usage that was "fine in beta." CareerVector must not be one of them.
• Architecture only degrades in production. The design that "barely fits" the free tier becomes the design that overruns the paid tier once usage scales.
• Free-tier discipline is a forcing function for resource-respecting design. Coalesce, hibernate, cache, throttle, P2P. Doing the right things in the small makes the system survive at large scale.
• A bill with a recurring line item we don't need is one we will forget to cancel.

If any architecture proposal requires a paid tier to function at all, reject it. Paid tier is for headroom and emergencies, never the floor.

This rule was hard-learned on 2026-04-28 when an agent provisioned Koyeb nano (paid) without authorization to work around an exhausted free slot. The service was deleted within ~10 minutes of discovery.

Vendor inventory

Cloudflare — primary platform (free tier)

Account ownership and IDs are operator-managed. Authenticate wrangler with an operator-owned Cloudflare account, and provide any required provider IDs through local environment variables or CI secrets. Do not commit provider IDs, emails, API tokens, or private local paths.

What CF runs:

The CF "spine" hosts data and reads. The split-vendor pattern (below) layers Deno on top for the WebSocket-shaped workload that CF can only serve via the limited DO free tier.

CF DO has a hard structural limitation: WebSockets on Workers can only be accepted via Durable Objects. There is no non-DO WebSocket path on Cloudflare. This is the one capability where CF's free tier is structurally weaker than alternatives.

Deno Deploy — secondary platform (free tier)

The Deno Deploy project is operator-managed. Provide DENO_DEPLOY_TOKEN through the local shell environment or CI secrets. Do not commit Deno tokens or private local paths.

What Deno runs:

Deno sits second in the relay list because its free tier is small. At 100k DAU, Deno's free tier (15 CPU-hours/month, 20GB bandwidth) cannot absorb the full WS traffic on its own. CF DO has the headroom; Deno does not. The client RelayWalker (see REALTIME-ARCHITECTURE-V3.md §"Resilience: multi-vendor relay") starts at the cf entry and advances to deno on open-failure or two consecutive abnormal closes after a successful open. Wraps to cf after the last entry, emitting relay_cycle_all_failed telemetry. There is no separate health-driven re-probe — the walker stays where it lands until it next fails, and a fresh tab restarts at index 0.

Practically: Deno carries traffic only when the cf entry fails for that tab. CF DO outages and CF-side quota burns are rare → Deno's free tier is wildly overprovisioned for this duty.

Hard rule for Deno: NEVER provision a paid Deno tier. If load on Deno trends toward the free cap, the right response is to fix the upstream issue (CF DO outage, runaway client retry loop) rather than upgrade.

WebSocket billing model on Deno is undocumented but the protocol-layer reading strongly favors per-connection (1 request per WS upgrade, frames inside are not requests). The empirical answer doesn't change the deployment plan, so we don't need to confirm it.

Note: cockpit-side health probes hit careervector-relay-deno.corbet.deno.net directly because CF Workers' fetch loops on in-zone CNAMEs that route externally — the browser-visible URL is the symmetric deno.relay.careervector.corbet.ch, the probe URL is the upstream *.corbet.deno.net.

Koyeb — tertiary platform (FREE TIER ONLY)

The Koyeb organization is operator-managed. Provide Koyeb credentials through local environment variables or CI secrets. Do not commit organization IDs, API tokens, or private local paths.

What Koyeb runs:

Koyeb has exactly one free instance per account, and it is permanently allocated to typst.

Hard rules for Koyeb:

1. Never deploy a second Koyeb service. The free slot is taken. Any new service would land on paid tier. This has happened once (2026-04-28, the alt-relay incident). It must not happen again.
2. Never provision a paid Koyeb instance type (nano, micro, small, anything that isn't free). If a workload requires more than the free slot, deploy it on a different vendor instead.
3. Treat Koyeb as full. When asked to deploy something, the answer is "Koyeb is full — choose another vendor." There is no "we'll just use the smallest paid tier" workaround.

Koyeb deployment lessons:

• The Koyeb REST API does accept dockerfile mode (the typst service was migrated from buildpack to dockerfile mode via REST on 2026-05-18 when the bun migration broke buildpack autodetect). Earlier reports of "the API silently ignores dockerfile keys" appear to have been resolved upstream.
• Koyeb's GitHub App scoping cannot reach private repos in this account; if a deploy needs git source, it must come from a public repo.
• The CLI koyeb is a fine local tool but the dashboard UI is the source of truth for billing.

Koyeb is intentionally outside OpenTofu

The Koyeb Terraform provider cannot round-trip the live free-tier service safely.

Root cause: the typst service runs with scalings[].min: 0 (scale-to-zero) plus a sleep_idle_delay autoscaling target (the deep-sleep deferral that keeps the free-tier instance hibernated when idle). The Koyeb API returns sleep_idle_delay inside targets[], but terraform-provider-koyeb does not model it in autoScalingTargetSchema() (only average_cpu, average_mem, requests_per_second, concurrent_requests, request_response_time are present). The TypeSet write fails when the unknown field round-trips through the schema, killing the plugin mid-import. Tracked upstream as terraform-provider-koyeb #74 "Supporting pausing/scaling to zero via terraform".

Other SDK fields the provider does not model (would surface as drift after import, even if #74 were fixed): strategy.type (deployment strategy, e.g. ROLLING), mesh, proxy_ports, config_files.

Until #74 lands and the deep-sleep target becomes representable, Koyeb stays out of the fleet OpenTofu roots. Provisioning and lifecycle for the typst service live in:

Re-evaluate OpenTofu adoption when either of the following lands:

1. terraform-provider-koyeb adds sleep_idle_delay to autoScalingTargetSchema() (issue #74), OR
2. The Koyeb API gains a way to suppress sleep_idle_delay in service Read responses.

CrateDB — shared knowledge store

CrateDB Cloud (CRFREE) stores JobCache Core's shared knowledge layer: roles, ads, organizations, evidence, embeddings, reusable work cache entries and adapter runs. It also stores only the purpose-scoped pseudonymous participant facts and projections admitted by the two privacy seams; pseudonymous data is personal data, not “impersonal.” Product-local workspace/session identifiers, inverse maps, CVL/CL content, notes, files and live edge state stay in D1/R2. (CrateDB replaced CockroachDB as the hot DB in the 2026-06 cutover — see CRATEDB-MIGRATION.md; the Cockroach cluster is dormant, rollback only.)

Hard rules for CrateDB:

1. No direct workspace-facing API. Workspaces see resolved job projections from the web Worker, not role/ad rows.
2. Reducer-gated aggregation only. Workspace facts move upward only through named reducers in code.
3. Expensive work must use stable cache keys. Scrape, extraction, embedding, geocoding, route lookup, and matching should be reused whenever the input key matches.
4. Vector indexes are optional operational steps. The base schema can store embeddings; vector indexes are applied separately after the cluster is ready.

Alwaysdata — protected JobCache Core host

Alwaysdata runs the bundled Node 24 JobCache Core at the protected /core origin. The public App API and MCP peer run on Cloudflare Workers; Core never receives App session_id state. OpenTofu adopts the site, reconciles a non-secret launcher and a mode-0600 runtime file, and keeps the provider-visible site environment empty. Artifact promotion verifies SHA-256 before atomic replacement.

The obsolete Render service remains suspended and has no JobCache App domain. No paid Render or Northflank activation is part of the architecture.

Hard rules for Core hosting:

1. No private workspace/session data. Core receives strict public lookup input, purpose-scoped pseudonyms and verified lifecycle envelopes.
2. Scoped credentials. The Crate runtime principal is schema-scoped; control, participant lifecycle and CareerVector erasure-worker capabilities are pairwise distinct.
3. Bounded ingress. The Node adapter rejects request bodies above 2 MiB before Hono buffering, including chunked uploads.

GitHub — code hosting (free tier)

Repository ownership is operator-managed. Authenticate gh locally or CI with the minimum repository scopes required for the operation.

Free for public repos and a generous allowance for private. No infra-cost concerns. Mentioned here only because Koyeb deployments source from GitHub repos.

Other authenticated providers — not currently used in the production path

Potential operator-configured providers:

• Google Cloud (gcloud CLI) — has free-tier compute (Cloud Run: 2M req/month, WebSocket-capable). Not currently used by CareerVector. Available as future fallback if Deno + CF combination ever proves insufficient.
• Scaleway (scw CLI) — EU-anchored serverless, free tier exists. Same status: future fallback option.

The split-vendor pattern

            ┌──────────────────────┐
            │      Browser         │
            │                      │
            │  RelayWalker walks   │
            │  PUBLIC_RELAY_URLS   │
            │  [cf, deno, …]       │
            └──┬───────────────┬───┘
               │               │
   REST/HTTP   │               │   WebSocket (Yjs ops, signaling, awareness)
   reads+writes│               │   to whichever relay entry the walker is on
               │               │
        ┌──────▼─────┐    ┌────▼─────────────────────┐
        │ Cloudflare │    │ cf  : Cloudflare DO       │
        │            │    │       (`relay/cf/` worker,│
        │ Workers    │    │        cf.relay.…)        │
        │ D1         │    │ deno: Deno Deploy         │
        │ R2         │    │       (`relay/deno/`,     │
        │ Cache API  │    │        deno.relay.…)      │
        │ DO         │    │ (next entries append      │
        │            │    │  here without protocol    │
        │ FREE TIER  │    │  changes)                 │
        └────────────┘    └───────────────────────────┘

The structural property: CF holds the data, the relay list holds the connection layer. Every relay entry speaks the same Yjs sync subset. A single-vendor outage on any one relay does not take down both "what is the user's data" and "who else is editing right now" simultaneously.

This is multi-vendor resilience along a meaningful axis — not "primary + backup of the same workload" but N independent platforms that can each carry the connection layer alone, while a third concern (durable data) lives on none of their WebSocket paths.

Why the cf entry sits first

Earlier in the design discussion, "Deno-as-only-entry" was floated. The math kills it for Deno-as-sole-relay:

• 100k DAU × ~2 WS sessions/day × 22 days = ~4.4M sessions/month → 4× over Deno's 1M cap.
• WS connection wall-time → ~150 CPU-hours/month → 10× over the 15h limit.

Deno free tier doesn't fit the steady-state WS load above ~10–20k DAU. CF DO (with V3's load-shedding moves) fits comfortably at 100k DAU.

So the list order is:

• cf first because CF DO has the budget headroom to be the everyday relay.
• deno second because Deno's free tier easily covers the rare per-tab failover volume and its failure modes are uncorrelated with CF's.
• A third entry would be appended with a new vendor prefix (see V3 §"Vendor-prefix convention").
• Inverting the order would burn Deno's free tier while wasting CF DO's headroom.

Failure modes & degradation

The combined uptime calculation (assuming CF 99.99% and Deno 99.95%, independent failures) puts "at least one WS path available" at ~99.999995% — under 2 minutes/year of full WS-layer downtime.

V3 architectural disciplines (load-bearing)

These are enforced by the @cv/workspace-client SDK and (eventually) ESLint rules. Breaking any one of them collapses the cost model.

Discipline 1 — All mutations go through applyOp

No direct fetch('/api/workspaces/...'). No direct Y.Doc construction outside the SDK. Anyone touching workspace state imports @cv/workspace-client and calls client.applyOp(subDoc, op).

The SDK handles transport selection (HTTP for non-realtime, WS for live, P2P for direct human↔human), optimistic local apply, no-op-write skipping, batched D1 writes, and ETag-driven cache reads. Bypassing the SDK loses every one of those benefits and silently breaks the cost shape.

Lint rule (chunk G): ban fetch('/api/workspaces/...') outside the SDK. Ban new Y.Doc() outside the SDK and one allow-listed test file.

Discipline 2 — No background polling cadence

Polling is event-driven only:

• Tab opens → 1 read.
• Tab regains focus (visibility-change) → 1 read.
• User attempts an action → 1 read.
• Idle tick every ~5 minutes while focused.

That's ~5–10 reads per active session. Adding a setInterval(poll, 5000) to "make it feel responsive" turns 7 polls/session into ~2000 → 100× cost increase. Lint rule should flag any setInterval that touches the workspace API.

Discipline 3 — Coalesce mutations to logical units before writing

One D1 write per "user finished doing something" — drag-released, form-submitted, paragraph-pause. Yjs ops still emit per keystroke for P2P sync (where they're cheap), but D1 only sees the coalesced unit. The SDK's CoalesceBuffer (250–500ms trailing-edge debounce) does this.

Without this, every keystroke is a D1 row, and a 1-minute typing burst writes 60 rows. Coalesced, it writes ~1.

Cost model at 1M users / 100k DAU

$0.000008/user/month at 1M users. With the V3 squeeze list (optimistic local apply, sub-doc partitioning, zstd-19 compression, skip no-op writes, immutable cache key) applied, this drops further to ~$2–3/month.

The cost shape scales linearly with active multi-human concurrency, not user count. A 10× user growth that keeps the same active-concurrency profile costs ~10× nothing.

What lives where (services & their homes)

Hard rules — summary

1. Free tier only, every vendor, every time. No exceptions. Paid is for headroom, never the floor.
2. Koyeb is full. The free slot is typst. Never deploy a second service to Koyeb.
3. cf sits first in PUBLIC_RELAY_URLS, deno second. Deno's free tier cannot absorb being the everyday entry; CF DO has the headroom. Inverting the order burns Deno and wastes CF DO headroom.
4. No direct workspace mutations. Everything goes through @cv/workspace-client.
5. No background polling. Event-driven only. setInterval touching the workspace API is a code smell.
6. Coalesce mutations to logical units. One D1 write per user-meaningful action, not per keystroke.
7. Multi-vendor along a meaningful axis. Data on CF, connections on the relay list (cf, deno, …). No single-vendor outage takes both down.
8. Wire format is portable. No vendor-specific framing on the WebSocket protocol. Same Yjs sync frames work on every relay entry.

If a proposal violates any of these, reject it. If reality and these rules disagree, fix reality immediately.

Companion-perspective subdomains — one worker per perspective

Every companion perspective runs as its own Cloudflare Worker. None of the perspective paths exist on the main careervector-ui worker — visiting careervector.corbet.ch/status, /operations, /testing, /status/jobcache, or /operations/jobcache returns 404. Those path slots are intentionally free for any unrelated future use.

Each worker is a minimal SvelteKit + @sveltejs/adapter-cloudflare app deployed via wrangler versions upload && wrangler versions deploy. Each binds only the Cloudflare resources it actually needs (CV_DB and CV_BUCKET for the CareerVector perspectives; just env vars for the JobCache ones). Admin workers — every ops-{ui,api,mcp} and qa-{ui,api,mcp} for both products — hold ADMIN_TOKEN as a per-worker secret. The same value is set on every admin worker so a single sign-in carries across products via the shared .corbet.ch-scoped admin_session cookie.

Shared code (D1 health reader, JobCache HTTP probe, bearer auth gate, ledger readers) lives in @cv/perspective-shared (lib/perspective-shared/). Every perspective worker imports from there; nothing is duplicated across worker source trees.

Subdomain → worker bindings live as Cloudflare Workers Custom Domains (account-managed, PUT /accounts/{account}/workers/domains with override_existing_origin: true when rebinding). There are NO CF Transform Rules in this routing path anymore — every perspective worker serves at / directly. The previous transform-rule + reroute-hook + cache-bypass-plugin stack has been removed entirely.

Canonical Cloudflare and JobCache domain state lives in the fleet infra repository. cloud/tofu/cf-jobcache/ owns the EU App D1 and both live Worker custom domains; cloud/tofu/alwaysdata-sporewright/ owns the Core site and protected runtime reconciliation. Both workspaces converge to zero-change plans. Do not invent resource IDs in application configuration.

Why every perspective is its own worker

Earlier iteration tried to serve all perspectives from careervector-ui under host-based rewrites. That model required a Transform Rule per subdomain, a SvelteKit reroute hook, and a vite-time patch to bypass the Workers Cache API for subdomain roots. Every layer had its own failure mode. It also conflated "perspective" (an architectural boundary) with "path on the main app" (a presentation choice). Splitting each perspective into its own worker eliminates all the routing glue, frees every collision path on the main domain, and matches the perspective abstraction directly.

Cost: each worker has its own deploy cycle. Shared TS code lifted into @cv/perspective-shared keeps that cost flat.

Post-deploy verification

TOKEN="$(grep '\*\*Token:\*\*' ~/.agent/secrets/cv-ops-admin.md | awk -F'`' '{print $2}')"

# Main domain — app works, every perspective slot is free (404)
curl -s -o /dev/null -w "%{http_code}\n" https://careervector.corbet.ch/                       # 200
curl -s -o /dev/null -w "%{http_code}\n" https://careervector.corbet.ch/status                  # 404
curl -s -o /dev/null -w "%{http_code}\n" https://careervector.corbet.ch/operations              # 404
curl -s -o /dev/null -w "%{http_code}\n" https://careervector.corbet.ch/testing                 # 404
curl -s -o /dev/null -w "%{http_code}\n" https://careervector.corbet.ch/status/jobcache         # 404
curl -s -o /dev/null -w "%{http_code}\n" https://careervector.corbet.ch/operations/jobcache     # 404

# Public perspectives
curl -s -o /dev/null -w "%{http_code}\n" https://status.careervector.corbet.ch/                 # 200
curl -s -o /dev/null -w "%{http_code}\n" https://status.jobcache.corbet.ch/                     # 200

# Admin perspectives — 401 without token, 200 with
curl -s -o /dev/null -w "%{http_code}\n" https://ops.careervector.corbet.ch/                    # 401
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" https://ops.careervector.corbet.ch/    # 200
curl -s -o /dev/null -w "%{http_code}\n" https://qa.careervector.corbet.ch/                     # 401
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" https://qa.careervector.corbet.ch/     # 200
curl -s -o /dev/null -w "%{http_code}\n" https://ops.jobcache.corbet.ch/                        # 401
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" https://ops.jobcache.corbet.ch/        # 200

If you need to remove a subdomain

# List bindings (filter to careervector-ui)
curl -s -H "X-Auth-Email: $CF_EMAIL" -H "X-Auth-Key: $CF_API_KEY" \
  "https://api.cloudflare.com/client/v4/accounts/$ACCT_ID/workers/domains?service=careervector-ui"

# Delete by domain id (from the LIST response)
curl -s -X DELETE -H "X-Auth-Email: $CF_EMAIL" -H "X-Auth-Key: $CF_API_KEY" \
  "https://api.cloudflare.com/client/v4/accounts/$ACCT_ID/workers/domains/<DOMAIN_ID>"

Account ID + zone ID are in ~/.agent/secrets/cloudflare.md. Use the global API key for the Workers Domains endpoint — the scoped agent token only has DNS write permission, not Workers:Edit.

Cross-references

• REALTIME-DESIGN.md — broker contract for the relays (byte-relay mechanics).
• REALTIME-ARCHITECTURE-V3.md — multi-pathway resilience model + cost model.
• Operator runbooks outside this repository — vendor accounts, secrets index, machine inventory, Koyeb deployment gotchas, and Cloudflare CLI safety rules.