Skip to main content

Project Structure

work-loom/
├── apps/
│   ├── api/          — Fastify REST API server
│   ├── cli/          — wl command-line tool
│   ├── web/          — Next.js management UI
│   └── docs/         — Docusaurus documentation site
├── packages/
│   ├── types/            — Core TypeScript interfaces and enums
│   ├── manifest/         — Zod schemas for binding, lock, state, loomfile
│   ├── storage/          — Content-addressed blob storage
│   ├── auth/             — Authentication, OIDC validation, role-provider plugins
│   ├── config/           — Dotenv loading with variable expansion
│   ├── database/         — Drizzle ORM schema and PostgreSQL layer
│   ├── drift/            — Drift detection between desired and actual state
│   ├── environment/      — Typed environment variable definitions
│   ├── eslint-config/    — Shared ESLint configuration
│   ├── fetch-client/     — Typed HTTP client (native fetch wrapper)
│   ├── react-query/      — Pre-configured TanStack React Query wrapper
│   ├── registry/         — Package registry and version management
│   ├── sync/             — Local sync engine (plan, apply, approve)
│   ├── workloom-api/     — Generated API client, hooks, types, and Zod schemas
│   ├── workspace/        — Workspace service and resolver
│   ├── renderer-core/    — Renderer interface and utilities
│   ├── renderer-claude/  — Claude Code provider renderer
│   ├── renderer-codex/   — Codex provider renderer
│   ├── renderer-copilot/ — Copilot provider renderer
│   └── renderer-gemini/  — Gemini provider renderer
├── package.json      — Root monorepo config
├── pnpm-workspace.yaml   — Workspace definition
├── turbo.json        — Build orchestration
├── tsconfig.json     — Root TypeScript config
└── tsconfig.build.json   — Build-specific config

Package responsibilities​

@workloom/types​

All shared TypeScript interfaces: Package, PackageVersion, Asset, AssetType, Workspace, WorkspaceTarget, Provider, Binding, LockFile, StateFile, RenderedFileEntry, ReleaseChannel.

No runtime dependencies. Pure type definitions.

@workloom/manifest​

Zod schemas and file I/O for the four manifest formats:

  • loomfile.yaml — workspace package list
  • .loom/binding.toml — workspace pointer
  • .loom/lock.json — resolved desired state
  • .loom/state.json — local installed state

@workloom/storage​

Content-addressed storage abstraction. ContentStore interface with LocalFSStore implementation. SHA-256 hashing, gzip compression, metadata sidecars.

@workloom/auth​

Authentication and authorization. RFC 8628 device auth flow, OIDC token validation via JWKS, role-provider plugin system with registry, role mapping engine (many:1 external-to-internal with glob patterns), and built-in OIDC/Database/LDAP providers.

@workloom/database​

PostgreSQL schema via Drizzle ORM. Tables for organizations, users, user roles, role mappings (per-org overrides), packages, package versions, workspaces, targets, and revisions.

@workloom/environment​

Typed environment variable definitions with defaults, validation, and secret masking. Central registry for all configuration across apps.

@workloom/registry​

PackageRegistry for CRUD operations. VersionManager for immutable version creation and semver constraint resolution. In-memory RegistryStore with interface for future database adapters.

@workloom/workspace​

WorkspaceService for CRUD with revision bumping. WorkspaceResolver for resolving desired state — takes workspace config + registry, returns fully resolved package list with versions and provider assignments.

@workloom/renderer-core​

ProviderRenderer interface that all provider renderers implement. RendererRegistry for looking up renderers by provider. Header generator for ownership comments.

@workloom/renderer-claude​

Renders canonical assets to Claude Code file locations. Handles merging multiple packages into shared files like .claude/settings.json.

@workloom/renderer-codex​

Renders canonical assets to Codex file locations. Supports layered AGENTS.md for monorepo target paths.

@workloom/renderer-copilot​

Renders canonical assets to GitHub Copilot file locations. Combines instructions into .github/copilot-instructions.md and renders skills/agents as individual .instructions.md files.

@workloom/renderer-gemini​

Planned renderer for Google Gemini. Currently blocks all output in Phase 1, reporting planned files as blocked diagnostics.

@workloom/config​

Dotenv loading with variable expansion and environment normalization. Loads a cascade of .env files based on NODE_ENV and ENV values.

@workloom/drift​

Drift detection engine. DriftDetector compares render plans against the local filesystem. DriftReporter formats results for terminal or JSON output.

@workloom/sync​

Local sync engine. SyncPlanner builds action plans (write/delete/skip). LocalApplier executes plans atomically. Includes path validation, trust classification, and approval tracking.

@workloom/fetch-client​

Lightweight typed HTTP client built on native fetch. Module-level setBaseUrl() and setAuthToken() configuration. Used as the transport layer for generated API hooks.

@workloom/react-query​

Thin wrapper re-exporting TanStack React Query with pre-configured WorkloomQueryProvider defaults. Single version pin for the monorepo.

@workloom/workloom-api​

Auto-generated TypeScript client from the API server's OpenAPI spec via Kubb v4. Provides typed client functions, React Query hooks, TypeScript types, and Zod schemas for every endpoint.