Architecture Overview

Workloom is structured as a TypeScript monorepo with reusable packages and deployable apps.

System diagram

                    ┌──────────────────────────────┐
                    │          Workloom Web         │
                    │  package admin, approvals,    │
                    │  workspace assignments, drift │
                    └──────────────┬───────────────┘
                                   │
                                   │ shared renderer/registry APIs
                                   │
┌──────────────┐        ┌──────────▼───────────┐
│   wl CLI     │◄──────►│      apps/api        │
│              │ HTTPS  │ registry + bindings  │
│ init         │        │ workspace revisions  │
│ login        │        │ package metadata     │
│ bind         │        │ object service       │
│ pull         │        │ telemetry/audit      │
│ push         │        └──────────┬───────────┘
│ status       │                   │
│ sync         │          ┌────────▼────────┐
│ sync --check │          │ object storage  │
└──────┬───────┘          │ sha256 blobs    │
       │                  │ md/json/assets  │
       │                  └─────────────────┘
       │
       │ local deterministic apply
       │
┌──────▼─────────────────────────────────────────────┐
│ Local workspace / repo / monorepo                  │
│                                                     │
│ .loom/binding.toml                                 │
│ .loom/lock.json                                    │
│ .loom/state.json                                   │
│                                                     │
│ Generated provider projections:                    │
│   .claude/**                                       │
│   AGENTS.md / .codex/**                            │
│   .github/copilot-instructions.md (planned)        │
└─────────────────────────────────────────────────────┘

Monorepo packages

Package	Responsibility
@workloom/types	Core TypeScript interfaces and enums
@workloom/manifest	Zod schemas and I/O for binding, lock, state, loomfile
@workloom/storage	Content-addressed blob storage with SHA-256
@workloom/auth	Device auth flow, token management, dev JWT
@workloom/registry	Package registry, version management, semver
@workloom/workspace	Workspace service, resolver, desired state
@workloom/renderer-core	Renderer interface, registry, header generation
@workloom/renderer-claude	Claude Code provider renderer
@workloom/renderer-codex	Codex provider renderer

Apps

App	Stack	Purpose
@workloom/cli	Commander.js	wl CLI tool
@workloom/api	Fastify	REST API server
@workloom/web	Next.js 14 + Tailwind	Web management UI
@workloom/docs	Docusaurus	This documentation site

Build system

• pnpm workspaces for package management
• Turborepo for build orchestration with topological dependency ordering
• TypeScript strict mode throughout
• Vitest for unit and integration tests