Architecture
Workloom separates product semantics from file movement:
Registry packages define the canonical assets.
Workspace revisions choose which packages apply where.
Renderers produce provider-specific file plans.
Sync applies only approved, safe, Workloom-owned outputs.
Drift checks prove local state still matches desired state.
Repository Packages
| Package | Role |
|---|---|
packages/core | Shared providers, policies, diagnostics, and errors. |
packages/manifest | Zod schemas for packages and workspaces. |
packages/registry-client | Fixture-backed and HTTP-based registry client boundary. |
packages/registry-server | Hono-based API server with OpenAPI spec generation for packages, workspaces, auth, objects, audit, and telemetry. |
packages/fetch-client | Native fetch() wrapper with Bearer token injection, error normalization, and timeout handling. |
packages/react-query | Lean @tanstack/react-query v5 re-export with useRetryDisable and getCombinedStatus. |
packages/workloom-api | Kubb-generated typed client functions, React Query hooks, and Zod schemas from the OpenAPI spec. |
packages/persistence | SQLite snapshot store for durable registry state. |
packages/github | GitHub REST automation for Copilot instructions and coding-agent repository policy. |
packages/renderer | Central deterministic render-plan implementation. |
packages/sync | Path normalization, hashing, approval gates, and writes. |
packages/drift | Fixture-driven drift classification. |
packages/telemetry | Forbidden-field scan for telemetry payloads. |
Applications
| Application | Role |
|---|---|
apps/api | Hono server exposing the registry API on port 4050. Serves GET /v1/openapi.json for the auto-generated OpenAPI 3.1 spec. |
apps/web | React SPA (Vite, port 3050) consuming generated hooks via @workloom/workloom-api. API-mediated Supabase OIDC auth. |
apps/docs | Docusaurus documentation site. |
API Generation Pipeline
The API layer follows an OpenAPI-first generation pipeline:
Hono routes + @hono/zod-openapi
-> /v1/openapi.json (auto-generated spec)
-> kubb v4.37.8 code generation
-> @workloom/workloom-api (types, client functions, React Query hooks, Zod schemas)
-> apps/web consumes generated hooks
Generated code in @workloom/workloom-api is committed to the repo for IDE
support and CI diffing, but is fully derivable from the OpenAPI spec. Manual
edits to generated files are overwritten on the next generation run.
Authentication Architecture
Supabase OAuth server (IdP)
-> API brokers authorize/consent/callback (/v1/auth/oidc/*, PKCE, ES256)
-> API issues a wl_ session token
-> custom AuthProvider stores it; useAccessToken() exposes the Bearer token
-> setAuthToken() in @workloom/fetch-client (transport-level injection)
-> all API requests carry Authorization header
Alternative auth paths: device login flow (CLI) and CI tokens. (SAML and service accounts were removed.)
Transport Model
The transport model is HTTPS/object sync, not SSH or rsync. Content-addressed objects use sha256 verification, signed upload/download URLs, ETags, and range downloads.