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 and boundary constraints:
    • architecture/README.md
    • architecture/blueprint.ts
    • architecture/blueprint-graph.ts
  • Op catalog and apply:
    • lib/mutations/src/opsCatalog.ts
    • lib/mutations/src/apply.ts
    • lib/mutations/src/url-normalize.ts
  • Read/write helpers:
    • lib/domain/src/read-chain.ts
    • lib/domain/src/jobcache.ts
    • lib/domain/src/cell-origins.ts
  • Migration:
    • existing migration scripts under ui/scripts/
    • shared-corpus migrations under migrations/
    • migrations/drop-job-id-allocator.sql

Invariants:

  • ad_id is deterministic from normalized URL.
  • URL normalization and hash truncation are immutable post-ship.
  • Workspace human/agent writes go through job.* ops into workspace.jobs[job_id].attributes.
  • A workspace job entry is { url, attributes }.
  • System/pipeline scrape/extract writes shared ad facts through jobcache.
  • Role facts are aggregate/shared facts, not directly user-written workspace state.

Workspace Client

  • lib/workspace-client/src/client.ts
  • lib/workspace-client/src/sub-doc.ts
  • lib/workspace-client/src/optimistic.ts
  • lib/workspace-client/src/transport/http.ts

Contract:

  • lib/mutations, workspace-client, app routes, MCP, direct UI, and assistant tools must agree on operation names and sub-document routing.
  • Multi-operation edits use the canonical batch path; they do not dispatch partially committed operations one-by-one.
  • Optimistic state, server receipts, Yjs clocks, realtime fan-out, and undo must converge on the same final workspace state.

API Server Commit Path

  • lib/server/src/workspace-subdoc.ts
  • lib/server/src/workspace-ops.ts
  • api/src/routers/workspaces.ts — workspace REST routes (Hono), including GET /workspaces/:id/sub/:subDoc and GET/POST /workspaces/:id/jobs[/...]

Invariants:

  • Durable workspace writes go through workspace op application.
  • Missing sub-doc rows are corruption, not empty documents.
  • Read-only mirrors must reject writes.
  • job.create apply must ensure shared ad/role knowledge exists or enqueue that work.

Dashboard And Job Detail

  • ui/src/lib/components/dashboard/Dashboard.svelte
  • ui/src/lib/components/dashboard/table/DataCell.svelte
  • ui/src/lib/components/dashboard/job-detail/
  • ui/src/lib/pipeline.svelte.ts

The UI consumes resolved job projections rather than treating one rung of the role → ad → workspace tree as the complete fact.

Workspace Intelligence / Process Requests

  • lib/server/src/process-requests.ts
  • lib/server/src/dispatch-fallback.ts
  • api/src/lib/server/process-commands.ts
  • api/src/routers/workspaces.ts (/workspaces/:id/process-requests routes)
  • ui/src/lib/components/ui/WorkspaceIntelligence.svelte

Invariants:

  • Browser execution is the cheap path when a workspace tab is open.
  • Server fallback exists for headless/MCP user intent.
  • Process request IDs should key on (workspaceId, ad_id, stage) after the shared ad is known, while public/API language remains job.
  • Do not build a separate agent-only pipeline.

MCP

  • mcp/src/tools/add_job.ts
  • mcp/src/tools/update_job.ts
  • mcp/src/tools/delete_job.ts
  • mcp/src/tools/list_jobs.ts
  • mcp/src/tools/get_job.ts
  • mcp/src/tools/process-request-id.ts
  • mcp/test/

Contract:

MCP should speak public jobs: add/update/delete/list/get map to job.* ops and resolved workspace job projections.

AI connectors and clients

  • lib/agent-gateway/ — managed Codex App Server protocol, lifecycle, and fail-closed dynamic-tool broker.
  • lib/assistant-tools/ — bounded workspace context, JobCache search, canonical operations, receipts, and compensating undo.
  • careervector-tui/ — terminal client plus as-built managed connector runtime.
  • ui/ — browser client and target persistent chat rail.
  • ui/desktop/ — Tauri shell, native adapter/render/update seams.

Vendor-client authorization is device/connector state. The remaining BYOK and cascade paths are v3 compatibility code: keep their keys redacted and their tests safe, but do not extend them into v4 product functionality. Workspace links and active workspace/session/operation IDs are the CareerVector scopes; no account record may be introduced as a shortcut.

Management

  • management-policy, management, and management-accountability in architecture/blueprint.ts define the fourth-column rail.
  • status/, ops/, qa/, and wiki/ are contained Management perspectives.
  • Product-specific observations and commands cross typed boundaries; Management does not become a shared database or ambient superuser.

CVL

  • ui/src/lib/components/cvl/CvGenerator.svelte
  • ui/src/lib/components/cvl/CVLEditor.svelte
  • ui/src/lib/components/cvl/editors/
  • lib/mutations/src/apply.ts node/tailored handlers

Invariants:

  • CVL is a recursive Node tree.
  • DocumentStack-like shapes are projections, not a second truth.
  • Tailored CV/CL placement is under workspace.jobs[job_id].attributes.tailored_cv / tailored_cl unless the user explicitly decides to lift it.
Source: wiki/content/onboarding/03-hot-paths.md