System Overview
Workloom is a package manager for AI workflow assets—instructions, skills, hooks, MCP configs, provider settings—with enterprise governance built in. Think npm + Terraform plan/apply + provider-aware renderers + trust gates.
Core Architecture Flow
Canonical Packages
(versioned, immutable, org-scoped)
↓
Workspace Revision
(pinned versions per workspace)
↓
Render Plan
(deterministic diff: desired vs current)
↓
Provider-Specific Files
(.claude/settings.json, AGENTS.md, .cursor/rules/*, etc.)
↓
Drift Detection & Ownership Tracking
(SHA-256 hashing, 5-state model)
Design Invariants
Workloom operates under five non-negotiable design invariants:
-
Generated files are outputs, not sources of truth.
- Never edit projected files directly. Edit the canonical package and re-render.
- Drift detection catches accidental edits and prompts restoration.
-
Renderer determinism.
- Given identical inputs, renderers produce byte-identical outputs every time.
- Renderers are contract-tested against fixtures to enforce this invariant.
-
Trust gates are non-optional for high-risk asset classes.
- Hooks (executable), MCP servers (networked), tool permissions—all require explicit approval.
- No silent overwrites. No surprise shell commands.
-
The sync layer carries no semantics.
- The sync layer moves bytes and manifests; only renderers assign meaning.
- Semantic decisions (what a file means, where it lives, whether it needs approval) belong to providers.
-
No cycles in the package dependency graph.
- Enforced by the build system.
- Prevents version resolution ambiguity.
Package Dependency Direction
Dependencies flow in one direction only — no cycles are permitted.
core
├── manifest
│ └── renderer
│ ├── provider-claude
│ ├── provider-codex
│ ├── provider-gemini
│ ├── provider-copilot
│ ├── provider-cursor
│ ├── drift
│ └── telemetry
├── auth (role providers, OIDC, sessions)
├── db (Drizzle schema + queries)
├── environment (env var registry + typed process.env)
└── config (layered .env loading)
fetch-client ────> (standalone: fetch wrapper + types)
react-query ─────> (re-exports @tanstack/react-query)
workloom-api ────> fetch-client, react-query (Kubb-generated hooks + client)
apps/api ────────> core, auth, db, manifest, telemetry (Hono server)
apps/web ────────> workloom-api, react-query, auth, config, environment
apps/cli ────────> core, manifest, renderer, fetch-client, workloom-api
Tech Stack
| Layer | Technology |
|---|---|
| Language | TypeScript 5.8 (strict mode) |
| Runtime | Node.js 20+ |
| Package Manager | pnpm 9+ |
| Workspace Orchestration | Turborepo |
| Schema Validation | Zod 3.25 |
| CLI Framework | Commander.js 14 |
| API Server | Hono 4 + @hono/zod-openapi |
| API Client Generation | Kubb v4 (types, hooks, Zod schemas) |
| Data Fetching | React Query (@tanstack/react-query) |
| Auth | OIDC + iron-session + role providers |
| Database | PostgreSQL + Drizzle ORM |
| Testing | Vitest |
Phased Delivery
| Phase | Status | What Ships |
|---|---|---|
| Phase 0 | Complete | Schemas, fixtures, provider matrix, trust model, wl validate |
| Phase 1 | Current | CLI local loop — wl pull, wl sync, wl status, drift detection, Claude + Codex renderers |
| Phase 2 | Current | Hosted registry API (Hono), auth (OIDC + role providers), wl push, web dashboard, lock files |
| Phase 3 | Planned | Web UI — approval workflows, RBAC, diff preview |
| Phase 4 | Planned | Telemetry pipeline, usage analytics, drift dashboards |
| Phase 5 | Planned | Gemini + Copilot + Cursor renderers, desktop app (Tauri), marketplace |
Next Steps
- Deep dive into the rendering pipeline
- Understand the API server & code generation pipeline
- Learn about trust gates
- See packages and assets