Monorepo Workspace Guide

Catalog **deployable apps**, **shared packages**, how they connect, how to run them locally, and where to open source for each concern. This complements [packag

Purpose

Catalog deployable apps, shared packages, how they connect, how to run them locally, and where to open source for each concern. This complements package-graph.md (boundary rules) and core-architecture-thinking.md (philosophy).

Workspace Layout

Managed by pnpm (pnpm-workspace.yaml: apps/*, packages/*, tools/*) and Turborepo / Nx task orchestration (turbo run, pnpm nx).

prox-os/
├── apps/           # Deployable or standalone runtimes
├── packages/       # Shared libraries (imported, not deployed alone)
├── docs/           # Canonical documentation (synced to apps/docs)
├── scripts/        # docs sync, arch generators, quality checks
└── AGENTS.md       # Agent + contributor rules (stronger than this doc)

Deployable Apps

Path	Package	Role	Default dev	Key entry
`apps/os-shell`	`@prox-os/os-shell`	Browser OS shell: desktop, windows, registry, routing	`pnpm dev:os` (port 3000)	`src/index.tsx`, `src/apps/registry.ts`, `src/router.tsx`
`apps/api-worker`	`@prox-os/api-worker`	Cloudflare Worker API (Hono)	`pnpm dev:api`	`src/index.ts`, `wrangler.jsonc`
`apps/docs`	`@prox-os/docs`	Fumadocs site (mirrors `docs/`)	`pnpm dev:docs` (port 3100)	`content/docs/`, `source.config.ts`
`apps/ui-workshop`	`@prox-os/ui-workshop`	Storybook for `os-ui` / tokens	`pnpm dev:ui`	Storybook config under app
`apps/esmadrider-me`	`@prox-os/esmadrider-me`	Founder static site; iframe app	`pnpm dev:esmadrider-me`	Vite app; `VITE_PROX_OS_URL` for OS CTA

Why api-worker lives under apps/ not packages/: it is a deployable HTTP service with its own Wrangler config, env bindings, and production URL — same category as os-shell and docs, not a library consumed via import. Shared server logic belongs in packages/* (e.g. future packages/os-actions, packages/db).

Shared Packages (selected)

Path	Package	Role	Key entry
`packages/app-contract`	`@prox-os/app-contract`	Manifest, window, permission types (no React)	`src/index.ts`
`packages/app-registry`	`@prox-os/app-registry`	Iframe manifest templates + URL resolution	`src/manifests/*`
`packages/os-apps`	`@prox-os/os-apps`	Official OS apps (in-window UI)	`src/index.ts`, per-app `manifest.ts`
`packages/os-ui`	`@prox-os/os-ui`	Shell UI primitives	`src/index.ts`
`packages/design-tokens`	`@prox-os/design-tokens`	`--os-*` CSS + Tailwind bridge	`css/prox.css`
`packages/db`	`@prox-os/db`	Drizzle/Neon (planned)	schema TBD
`packages/storage`	—	Object storage abstraction (planned)	placeholders

How Pieces Connect

flowchart LR
  subgraph browser [Browser]
    Shell[apps/os-shell]
  end
  subgraph packages [Packages]
    Contract[app-contract]
    Registry[app-registry]
    OsApps[os-apps]
    OsUi[os-ui]
    Tokens[design-tokens]
  end
  subgraph deploy [Deployables]
    API[apps/api-worker]
    DocsSite[apps/docs]
    Workshop[ui-workshop]
    Founder[esmadrider-me]
  end
  Shell --> Registry
  Shell --> OsApps
  Shell --> OsUi
  Shell --> Tokens
  Registry --> Contract
  OsApps --> Contract
  OsApps --> OsUi
  OsUi --> Tokens
  Shell -.iframe.-> Founder
  Shell -.dev iframe.-> DocsSite
  Shell -.dev iframe.-> Workshop
  Shell -.future HTTP.-> API

OS Shell Internal Map

Concern	Location
App registry composition	`apps/os-shell/src/apps/registry.ts`
Local app renderers	`apps/os-shell/src/apps/localAppComponents.tsx`
Window + Spaces store	`apps/os-shell/src/window-manager/store.ts`
Shell controller	`apps/os-shell/src/shell/useDesktopShellController.ts`
Global shortcuts	`apps/os-shell/src/shell/GlobalShortcuts.tsx`
Cmd+K app list	`apps/os-shell/src/shell/command/commandPaletteApps.ts`
Boot appearance	`apps/os-shell/src/browser-local/applyBootShellAppearance.ts`
Session / login overlay	`apps/os-shell/src/shell/session/*`
Design tokens on `<html>`	`shell/settings/useShellSettingsState.ts`

Common Commands

pnpm install
pnpm dev:os          # OS shell
pnpm dev:api         # API worker (Wrangler)
pnpm dev:docs        # docs:sync + Fumadocs dev server
pnpm dev:ui          # UI workshop / Storybook
pnpm typecheck
pnpm lint
pnpm docs:sync       # docs/ → apps/docs/content/docs
pnpm build:docs
pnpm arch:check      # dependency-cruiser boundaries

Repo-wide tasks prefer turbo run <task> per AGENTS.md.

Production Domains (direction)

Official subdomains are infrastructure entrypoints, not per-app identity. Creator-owned path namespaces are the preferred long-term model for public app URLs. See app-namespace-and-domain-strategy.md.

Host	Typical deployable	Shell visibility
User OS	`apps/os-shell` (Pages)	Primary product
`api.prox-os.com`	`apps/api-worker`	HTTP client from apps; not embedded as UI
`docs.prox-os.com`	`apps/docs`	Public docs; dev team may also use `/app-dev/docs` iframe locally
`ui.prox-os.com`	`apps/ui-workshop` build	Design QA; dev iframe in shell
Scalar / OpenAPI	Often `api-worker` `/docs` or separate	Production: omit from user registry; use `/app-dev/*` + Cloudflare Access

See cloudflare-deploy-and-access.md for the Cloudflare project names, Access boundaries, API docs exposure policy, and manual dashboard follow-up.

Adding a New App (checklist)

Implement under packages/os-apps (or shell local-module if shell-coupled).
Add manifest to apps/os-shell/src/apps/registry.ts and types.ts ShellAppId.
Wire localAppComponents.tsx and packages/os-ui ShellAppIcon if needed.
Cmd+K picks up registry automatically via getCommandPaletteApps().
Update app-registry.md and run pnpm docs:sync if user-facing docs change.

See .agents/skills/prox-os-shell-workflows/SKILL.md for the full shell checklist.

Monorepo Workspace Guide

On this page