Ideas and architecture

CareerVector UI shell The CareerVector UI lives under ui/ as a SvelteKit app that SSRs on Cloudflare Workers, hydrates in the browser, and persists durable state through the @cv/workspace client SDK to D1 and the real...

Cloudflare Workers quota policy CareerVector ships its public surface on Cloudflare Workers. The free tier budget is 100,000 requests per day, account wide — shared across every Worker on the account. That single numb...

Collaborative prose as Y.Text — and what stays Y.Map CareerVector's collaboration model assumes more than one author per field at any moment. A friend rephrases a bullet while the user keeps typing the next one; a men...

Compute Backend — one engine, many hosts, no drift CareerVector splits "what to execute" from "where to execute it." The engine is one TypeScript module tree under lib/domain/src/pipeline/stages/; the backends are the...

Cutover migration, job id convention, jobs boundary, two step deploy This page collects four related "shape of the world" decisions that otherwise float around the repo without a canonical home. Cutover from the legac...

JobCache participant UI The scraping pill is a compact status and consent control in the right side of CareerVector's workspace action band. It projects a participant owned by the application root. Mounting, opening,...

LLM Cascade — one resolver for every model and service call The cascade is the single way every model or service call in CareerVector picks a provider, a model, and an API key. Importing a provider SDK directly, readi...

No User Accounts — workspace as the collaboration unit CareerVector deliberately has zero authentication. There is no login, no registration, no profile, no admin role, and no per user permission. This is a product de...

Op Catalog — typed writes, one broker contract lib/mutations/src/opsCatalog.ts is the single source of truth for every write CareerVector can make to a workspace. Anything that mutates Yjs state flows through it: the...

Per job pipeline machine, unified editor, per language quarry Per job pipeline machine ui/src/lib/pipeline.svelte.ts is the browser backend of the process request queue. It runs one xstate machine per job through five...

Quarry Pattern — content pool, three mutability tiers, deterministic identity The quarry pattern is CareerVector's core document generation idea. The user maintains a single content pool (the "quarry") containing ever...

RADAR — automated job discovery into the workspace RADAR is the entry point for jobs that the user did not paste manually and that did not come from MCP or a collaborator. It is one of the pipeline stages defined in l...

Read only mirror and workspace intelligence projection Mirror by URL pattern The /view/[wsId]/... route tree is the sanctioned read only view of a workspace. It is not a fork, not a snapshot, not a separate workspace...

Realtime resilience — many transports, one leader, cached snapshots CareerVector's realtime channel is the path collaboration takes. It must survive vendor incidents (CF or Deno regional outages), corporate firewalls,...

Scoring & Views — three input categories, rule based groups, immutable order The dashboard's two main decision aids are scoring and views. Both are designed so users can rank and group hundreds of jobs without the sys...

Testing architecture — story driven, local first, deployed target bounded CareerVector's testing strategy is a stack, not a single tool. Each lane exists because a kind of mistake would otherwise reach production. The...

Tiered telemetry — RED, YELLOW, diagnostic CareerVector has no user accounts, so it cannot beg permission on signup or attach a user level consent record. Telemetry is workspace scoped and graduated by impact so the d...

Typst Client Render — render economics, font system, design canon Document compilation happens in the browser, never on the server. The Typst WASM compiler + renderer (~25 MB) is lazy loaded from a CDN on first use; f...

Work Queue + Singleflight — three concurrency layers, one stack CareerVector coordinates concurrent work at three different granularities. They are layers of the same stack, not alternatives. Confusing them is the fas...

Adapter Code Inventory Current state: all shipped ingest sources are direct Adapters that emit the canonical Observation shape. There is no second submitted output shape and no portal wrapper layer in the ingest tree....

Adapter Contract An Adapter is a language neutral dock contract. It names how JobCache hands bounded work to source specific code and how an Observation comes back. The implementation behind the dock is a blackbox. It...

Adapter Dock What this is The Adapter dock is the language neutral Rust contract every job source observer plugs into. One implementation per source (or per source produced by a multi tenant family factory) discovers...

Adapter Slice Plan Rule for every slice: it ships one coherent Adapter path, validates through ObservationSchema, and deletes any same source code it replaces. No parallel submitted shapes and no compatibility layer l...

Admin Gate Auth jobcache ops api, jobcache ops mcp, and ops.jobcache.corbet.ch share one admin secret. The gate code lives in the ops API; the MCP and UI cookies fan out to that gate, so there is only one secret to ro...

Analytics Layers This note fixes vocabulary around analytics surfaces. The product can ship without the user facing analytics tab, but the names must stay clear so later work does not mix product analytics, platform i...

Architectural Principles Non negotiable. Every decision runs through these. 1. Compute economics (priority order) 1. Reduce work first. Don't do work that doesn't need doing. Cache, dedup, lazy load, skip when unchang...

Architecture The shape of the active CareerVector codebase. Stack at a glance Layer Choice Why Front end framework Svelte 5 Smallest bundle, fastest runtime, smallest per component scope (good for AI agents to write)....

Architecture JobCache is a bun workspace tree with an observer private App zone and a shared Core zone. api/ and mcp/ are live Cloudflare Workers; interface/ is the protected Core HTTP process; shared/ is the Core dat...

Architectures — Delivering Cockpit Data The cockpit must compose three streams of evidence: 1. Snapshot — point in time aggregates (queue depth, counts, latency of last probe). Cheap to compute, expensive if computed...

Broker Flow HISTORICAL (broker lane abandoned). The active transport is the orchestrator: devices POST /lease for targets (including discover targets), scrape, deposit results to B2, and notify via POST /deposited; di...

Browser & Device Compatibility Audit — v2 Audit date: 2026 04 26. Methodology: static code analysis + caniuse style reasoning. No live browser testing. 1. Declared Targets vs Reality No .browserslistrc, no Browserslis...

BYOK Encryption — Client Side Key Protection Design Status: LOCKED. This document records the design, threat model, and phased implementation plan for encrypting BYOK AI provider API keys at rest in D1. Implementation...

CareerVector — Architecture Technical architecture decisions that flow from the business model in studies/business model/README.md. Covers the data model, system surfaces (Browser UI / REST API / MCP), the relationshi...

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

CareerVector / JobCache Resource Map Status: repo derived inventory, last reviewed 2026 05 30. This is the operator map for active and near active infrastructure. It is not a secret inventory and not a full provider a...

CareerVector Analytics Event Catalog Status: CANONICAL. This document is the contract for all telemetry emitted by CareerVector. Every event type must appear here before shipping. Adding a new event without updating t...

CareerVector LLM tensor routing CareerVector applies Sporewright independently of JobCache. Both systems use the same generic addressed field mathematics, but they have different addresses, observations, persistence,...

CareerVector product thesis CareerVector is a private career intelligence workspace connected to a collectively maintained, real time model of the job market. It finds opportunities, explains fit and builds truthful a...

Cloudflare Workers Limits Audit Sources reviewed: relay/cf/src/workspace doc.ts — Durable Object broker api/src/routers/ .ts — REST handlers (Hono workers; workspaces.ts, misc.ts, llm.ts, telemetry.ts, p2p.ts, interna...

CockroachDB — Hot Store + CF Worker Access SUPERSEDED (2026 06 08). The canonical hot store is now CrateDB Cloud CRFREE (West Europe, Azure; pg wire only — no JSONB/txns/FK; dialect contract in jobcache/shared/src/pg...

Control plane — the thin orchestrator The principle: the genius is in the math, not in fat workers. The control plane moves data and runs cheap math. It never inspects content, never validates payloads, never keeps a...

CrateDB Migration (jobcache) Status as of 2026 06 07. jobcache is moving its hot DB off CockroachDB Cloud (RU disabled) onto CrateDB Cloud (CRFREE) . CareerVector is unaffected — it runs on Cloudflare D1; only jobcach...

CVL Open Questions Status: historical decision companion This page keeps the anchors referenced by Tree of Choices and records which questions are still live. It is intentionally short: resolved items belong in the de...

Desktop App Architecture Status: Phase 1 Linux MVP fully wired. The Tauri v2 shell ships, 88 adapter families are linked into the router (Waves 0 3 complete), TauriEnv::fetch rendered is implemented via a hidden Tauri...

Desktop Edge Runtime Proposal Jobcache should treat the desktop app as an optional edge runtime, not as a second product. The user visible CareerVector app stays Svelte/TypeScript; the desktop build adds a native Taur...

Device Contract This document defines the boundary for distributed jobcache devices. It does not define adapter implementation. Source specific fetch and parse code can be built by another agent or team as long as it...

Device QA Distributed device execution needs QA from day zero because defects here can pollute shared ad and role state. QA treats the device, session, task, lease, Observation, current ad payload cells, and global de...

Env Fetch Router — Cheapest First Cascade JobCache has to handle a mixed source landscape: friendly direct pages, JS rendered boards, and hostile detection heavy boards. Paying browser backed rates for an HTML only pa...

Fleet routing — the tensor as navigator Companion to [[CONTROL PLANE]] (orchestrator internals: queue, lease, deposit, ingest) and [[SCRAPER FLEET]] (host classes + rebuild requirements). This doc is the ROUTING desig...

Free Container Provider Inventory This page tracks external capacity for JobCache Devices. A provider is useful only if it can run brokered work without receiving Cockroach, B2, R2, S3, or provider credentials. Every...

Free Tier Infrastructure JobCache is a peer product, not a hosted SaaS. It pays for itself by operating inside the free tier of every vendor it uses. That constraint shapes a lot of decisions that look strange in isol...

Glossary Use these words consistently. Each word should mean one thing. Source Catalog family: reusable job site type, such as Workday, Greenhouse, jobs.ch, RSS, or custom HTML. source: concrete job site, board, compa...

Graph Metadata Editor Status: design contract. The editor works on graph claims, not raw file formats. A human or agent edits the same conceptual object everywhere: The backing writer decides whether the change eventu...

Ingest Architecture Draft JobCache is the top down ingest trigger for CareerVector's job knowledge graph. It should learn aggressively from proven Swiss job aggregation systems, especially their scraping process and s...

JobCache ↔ CareerVector relationship Status (2026 08 17): both edge installations and the relevant Core boundaries exist in code. CareerVector is the first deployed installation. JobCache App's Worker/D1/MCP and the n...

JobCache Architecture Status (2026 08 18): the API first architecture is implemented, migrated and live. JobCache Core's corpus/search facade and participant lifecycle run from jobcache/interface/ on a protected Alway...

JobCache Dashboard — product vision (STUB) Status: STUB. This page records the agreed direction and intentionally does NOT enumerate the dashboard's tabs. The tab set is an open product decision (task 72) and must be...

JobCache host routing JobCache no longer multiplexes its public API, MCP and UI through one Render process. The public product perspectives are separate Worker peers; Core is a protected origin behind the App boundary...

JobCache ingestion and CareerVector consumer AI These are two independent systems that share Sporewright's mathematics. They do not share a tensor, queue, identity, feedback log, or persistence boundary. JobCache rout...

JobCache perspectives — hosts, packages and deployment JobCache is one product with an observer private App zone and a shared Core zone. App API, MCP, UI, status, ops, QA and wiki are peer perspectives; “Core” is a co...

Jobich Gap Analysis This is a behavioural study, not a code reference. Jobich is the proven Swiss job aggregation reference; we have no licence to its code. Every observation below is described in our vocabulary (Adap...

Local AI pill Product intent Local AI should become available on as many capable devices as possible, but a multi gigabyte model must never download without informed consent. The product therefore separates instant va...

Observability — Push to Vendors, Pull /metrics for Cockpit JobCache has two distinct observability paths. One pushes structured logs and traces to vendor dashboards (Sentry, Grafana Cloud) for incident forensics. The...

Observation JobCache receives @cv/jobcache Observation envelopes from top down devices and safe bottom up CareerVector imports. Both paths emit the same ad id centered shape; workspace jobs remain private. There is on...

Operator Actions — Append Only Audit Every mutating endpoint in jobcache ops api writes a row to operator actions before dispatching the actual upstream call. The MCP wraps the same endpoints, so MCP driven recovery i...

Package Contracts Two internal packages carry contracts that other perspectives depend on existing and behaving exactly as documented. They are small, frozen, and load bearing. This page is the canonical description o...

Privacy posture and data minimization Status: normative engineering policy with both product edge lifecycle implementations present in code. Production activation still requires the additive D1/CrateDB migrations, sco...

Private product edges / JobCache Core boundary Status: implemented, migrated and live at both product edges and the JobCache Core API. The App Worker/D1, scoped credentials, scheduled erasure drain and public API/MCP...

Product engine — shared mechanism, separate products Aligned 2026 08 17. CareerVector and JobCache are two product domains. They reuse code where the mechanism is genuinely the same; they do not collapse their meaning...

QA Platform Design The architectural spec for the QA platform at qa/{ui,api,mcp}/ (CareerVector) and jobcache/qa/{ui,api,mcp}/ (jobcache). Operator dashboard, machine API, and AI agent MCP surface for orchestrating te...

QA Surfaces JobCache's QA platform follows the same three worker shape used everywhere else in the repo: API for state, MCP for agents, UI for humans. The shape is intentional — every product (CV, JobCache, future one...

RADAR Architecture RADAR is the CareerVector to JobCache feature slice: how a JobCache role reaches a person and how purpose approved feedback returns. For compactness this diagram combines JobCache App and JobCache C...

REALTIME ARCHITECTURE V3 — Multi Pathway, Actor Aware, Cost Bounded Status: deployed — the waves landed on main (cvl node tree direct merged 2026 05 16). Supersedes the hot path sections of the retired REALTIME ARCHIT...

⚠️ HISTORICAL DESIGN. The body below describes the pre byte relay broker design (op validation at ingest, DO SQLite persistence, D1 cold backup). It was superseded by the live thin byte relay: the WorkspaceDoc DO (rel...

Rust + WASM Adapter Architecture End state proposal for the JobCache Adapter dock. Written for Codex review — Codex owns the contract crate, WIT source, host shim, and build pipeline. Adapter implementer (me) owns the...

Scrape Event Log scrape events is JobCache's append only operational pulse. Device runtimes and trusted operator owned harnesses report one row per leased scrape attempt through the control plane; the ops API reads fr...

Scraper Fleet The collection side of JobCache. [[CONTROL PLANE]] is the orchestrator internals, [[FLEET ROUTING]] is the M2 tensor routing design (locked 2026 07 02: archetype options, trust mechanics, budget λ, occup...

Server framework — Hono for backend perspectives Decision date: 2026 05 16 Decision owner: Julian, after architecture discussion Status: Adopted; migration in progress TL;DR Pure REST and pure RPC perspectives (api, m...

Source Coverage Catalog Canonical per family source list for the JobCache adapter rollout. Every entry maps to one row in a Rust adapter crate's SOURCES const (or a single source Adapter's hardcoded constants). Status...

System Architecture There are two products and three privacy/runtime zones . JobCache App is the observer facing product edge. JobCache Core is JobCache's shared corpus, search, recommendation and market intelligence...

The Shared Seam Packages Status (2026 08 17): @cv/corpus shared is integrated by CareerVector, JobCache Core and the new JobCache App. Pure participant/privacy/search/snapshot/fact/delivery/lifecycle contracts are sha...

Tier 2 Headless Fleet — implementation spec ( 68) Generated 2026 06 08 by the tier2 headless fleet workflow. The buildable plan; Browserbase OUT, fully self hosted. Recommended free 512MB target Oracle Cloud Always Fr...

Tier 2 Headless Ingestion ( 68) Decision (2026 06 07): JS rendered + hostile boards are scraped by a self hosted fleet of Playwright pods on k3s , called by a lean Rust device (thin client). No managed/external headle...

Tree of choices — Canonical design record Overview The core idea is that a CV or cover letter is a recursive tree where each node holds a pool of candidate children and a selection (which to render and in what order)....

UI Taxonomy CareerVector's shared frontend components live in three lib/ packages, split by audience and quality bar. The split keeps product polish out of admin surfaces (where the cost would be unjustified) and keep...

Vocabulary Canonical definitions for terms that appear in code, UI copy, agent prompts, and operator chatter. The goal is to prevent drift: if you read one of these words in a code comment, in a Svelte template, in an...

Wiki App Shape The wiki perspective (wiki.careervector.corbet.ch) is one site presenting the same knowledge mesh through six primary entry points. The shape of the app — its tabs, its index, its host — is intentional,...

Wiki Knowledge Mesh The Wiki should be one mesh, not one wiki per product. QA and Ops stay separate as products and deployments. A CareerVector QA queue is not a JobCache QA queue. A CareerVector Ops anomaly is not a...

Architectures — Delivering Cockpit Data The cockpit must compose three streams of evidence: 1. Snapshot — point in time aggregates (queue depth, counts, latency of last probe). Cheap to compute, expensive if computed...

CareerVector — Architecture Technical architecture decisions that flow from the business model in studies/business model/README.md. Covers the data model, system surfaces (Browser UI / REST API / MCP), the relationshi...

CareerVector business model The decision CareerVector is free, permanently. It must never cost its users a cent. This is not a temporary launch offer, a free tier or a funnel into a paid applicant product. CareerVecto...

CareerVector Cockpit — Concrete Views This file describes the cockpit views for ops.careervector.corbet.ch (and the projection that lands on status.careervector.corbet.ch), assuming the recommended hybrid architecture...

Cloudflare AI Gateway fit for CareerVector Status: research memo, 2026 05 19. This note evaluates Cloudflare AI Gateway against CareerVector's AI model: browser/client BYOK calls where possible, server key calls only...

Cockpit Vision Status: draft. Not normative. Use as the working brief for the status/, ops/, and qa/ perspective workers (and their JobCache counterparts) until concrete decisions land in wiki/content/architecture/. E...

DevOps Wiki Product Vision Status: draft product vision Date: 2026 05 19 The wiki should become the glue between product vision, implementation, quality, and operations. It is not just a document site. It is the share...

FinOps Runway Contract Status: draft implementation note for the ops cockpit. The FinOps tab should not make Svelte components rediscover operational meaning from raw vendor rows. The API owns the projection. UI, MCP,...

JobCache Dashboard — product vision (STUB) Status: STUB. This page records the agreed direction and intentionally does NOT enumerate the dashboard's tabs. The tab set is an open product decision (task 72) and must be...

JobCache Ops — Concrete Views JobCache is CareerVector's sister product, sharing the role → ad → workspace job fact tree (CLAUDE.md sibling repo notes; jobcache repo .agent/AGENT.md). Today it focuses solely on extrac...

Naming the Corpus A commercial naming study for the CareerVector job postings corpus product 2026 05 08 Executive summary The product is a continuously scraped, deduplicated, normalized, embedded corpus of job posting...

Ops & Status v1 Product Brief This brief captures the first implementation target for the CareerVector operations cockpit after the auth spike was set aside. It is the product contract for the first useful version, no...

Ops Vendor Inventory Sweep — 2026 05 19 Status: implementation note for the ops cockpit inventory sprint. This sweep looked at three sources without copying secret values: Runtime code and wrangler.toml bindings. Exis...

QA Platform Product Vision Status: product vision plus first local MVP slice Date: 2026 05 19 Implementation note 2026 05 19 First API slice now exists in the shared QA platform library: GET /v1/runner/policy reports...

Telemetry Tiers — Green / Yellow / Red This note formalizes the consent model the cockpit relies on. It builds on the tier names already in the code (ANALYTICS EVENT CATALOG.md) but extends them from "build flag bundl...

Vision — The Cockpit A cockpit is what an operator sits in front of when the system is alive. It shows what is happening now , what was happening a moment ago, where the attention is needed, and what levers exist. It...

CareerVector AI Onboarding This folder is durable onboarding context for AI agents working on this checkout. It is intentionally short, current, and more stable than temporary task handoff notes. Start Here 1. Read th...

CareerVector Efficiency Stories This catalog covers cost, quota, latency, and operational efficiency. User stories say what the user can accomplish. System stories say what platform guarantees make that possible. Effi...

CareerVector Repository Operating Contract This document is the orientation sheet a new contributor (human or agent) should read after CLAUDE.md. It explains how the repository is laid out, which files are load bearin...

CareerVector System Stories This catalog covers stories the system must guarantee so user stories remain true. User stories describe visible applicant and collaborator goals. System stories describe platform behavior,...

CareerVector User Stories This catalog enumerates the user stories CareerVector needs to guarantee semantically. It is the input to the testing architecture, not the architecture itself. Each story is written in user...

Current Architecture This file describes the careervector cvl checkout as of 2026 05 12. Stable Architecture CareerVector is a SvelteKit app on Cloudflare Workers with D1/R2, a realtime Durable Object relay, MCP worke...

Hot Paths Use this before editing. It is a map, not a substitute for reading live code. Prefer rg over trusting line numbers. Data Model Product/business constraints: studies/business model/README.md studies/architect...

Product North Star The canonical product thesis, including the role of JobCache, AI and the open strategic questions, is architecture/PRODUCT THESIS.md. This page is the concise contributor contract. CareerVector is a...

Story coverage waivers The audit script scripts/audit story coverage.ts separates traceability from green status: GREEN means every current Critical/High story is covered without debt. PASS WITH DEBT means every Criti...