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 Nx task orchestration (pnpm nx). Nx owns the project graph, affected task selection, target defaults, and local cache.

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/data/db).

Shared Packages (selected)

Path	Package	Role	Key entry
`packages/contracts/app-contract`	`@prox-os/app-contract`	Manifest, window, permission types (no React)	`src/index.ts`
`packages/os-surface`	`@prox-os/os-surface`	Desktop Surface Engine model, layout modes, surface capabilities, and placement shapes	`src/index.ts`
`packages/runtime/app-registry`	`@prox-os/app-registry`	Iframe manifest templates + URL resolution	`src/manifests/*`
`packages/ui/actions`	`@prox-os/actions`	Action intent contract and UI primitives	`src/index.ts`
`packages/ui/command`	`@prox-os/command`	Command contract and palette primitives	`src/index.ts`
`packages/ui/forms`	`@prox-os/forms`	Form contract, validation, and input primitives	`src/index.ts`
`packages/ui/editor`	`@prox-os/editor`	Editor contract and adapter primitives	`src/index.ts`
`packages/features/collaboration`	`@prox-os/collaboration`	Collaboration contract and UI primitives	`src/index.ts`
`packages/ui/notifications`	`@prox-os/notifications`	Notification contract and UI primitives	`src/index.ts`
`packages/features/search`	`@prox-os/search`	Search contract, local adapter, and UI primitives	`src/index.ts`
`packages/features/files`	`@prox-os/files`	File contract, browser primitives, previews, picker, and transfer-state UI	`src/index.ts`
`packages/features/ai-ui`	`@prox-os/ai-ui`	AI interaction contract, chat/tool/approval/artifact/context/citation primitives	`src/index.ts`
`packages/features/security-ui`	`@prox-os/security-ui`	Security UI contract, permission/risk/audit/session/token/access review primitives	`src/index.ts`
`packages/features/workspace-ui`	`@prox-os/workspace-ui`	Workspace UI contract, switcher/dashboard/resource/member/project primitives	`src/index.ts`
`packages/ui/activity`	`@prox-os/activity`	Activity timeline contract, feed/digest/detail primitives, and cross-domain adapters	`src/index.ts`
`packages/contracts/data-contract`	`@prox-os/data-contract`	Structured dataset, view, source, and chart types (no React)	`src/index.ts`
`packages/features/data-table`	`@prox-os/data-table`	OS-native table/grid primitives	`src/index.ts`
`packages/features/data-viz`	`@prox-os/data-viz`	OS-native chart primitives and adapters	`src/index.ts`
`packages/features/media`	`@prox-os/media`	Media resource contract and UI primitives	`src/index.ts`
`packages/features/maps`	`@prox-os/maps`	Map/geospatial contract and UI primitives	`src/index.ts`
`packages/apps/system-apps`	`@prox-os/os-apps`	Official OS apps (in-window UI)	`src/index.ts`, per-app `manifest.ts`
`packages/ui/os-ui`	`@prox-os/os-ui`	Shell UI primitives	`src/index.ts`
`packages/ui/design-tokens`	`@prox-os/design-tokens`	`--os-*` CSS + Tailwind bridge	`css/prox.css`
`packages/data/db`	`@prox-os/db`	Drizzle/Neon (planned)	schema TBD
`packages/backend/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]
	    OsSurface[os-surface]
	    Actions[actions]
    Command[command]
    Forms[forms]
    Editor[editor]
    Collaboration[collaboration]
    Notifications[notifications]
    Search[search]
    Files[files]
    AiUi[ai-ui]
    SecurityUi[security-ui]
    WorkspaceUi[workspace-ui]
    Activity[activity]
    Registry[app-registry]
    DataContract[data-contract]
    DataTable[data-table]
    DataViz[data-viz]
    Media[media]
    Maps[maps]
    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 --> OsSurface
	  Shell --> OsUi
	  Shell --> Tokens
  Workshop --> Actions
  Workshop --> Command
  Workshop --> Forms
  Workshop --> Editor
  Workshop --> Collaboration
  Workshop --> Notifications
  Workshop --> Search
  Workshop --> Files
  Workshop --> AiUi
  Workshop --> SecurityUi
  Workshop --> WorkspaceUi
  Workshop --> Activity
	  Registry --> Contract
	  Contract --> OsSurface
	  OsApps --> Contract
  OsApps --> OsUi
  DataTable --> DataContract
  DataViz --> DataContract
  Workshop --> DataContract
  Workshop --> DataTable
  Workshop --> DataViz
  Workshop --> Media
  Workshop --> Maps
  Command --> Actions
  Forms --> Actions
  Collaboration --> Actions
  Notifications --> Actions
  Notifications --> Collaboration
  Search --> Actions
  Search --> Command
  Search --> Collaboration
  Search --> Notifications
  Files --> Actions
  Files --> Search
  Files --> Notifications
  Files --> Collaboration
  AiUi --> Actions
  AiUi --> Editor
  AiUi --> Search
  AiUi --> Files
  AiUi --> Notifications
  AiUi --> Collaboration
  AiUi --> Command
  SecurityUi --> Actions
  SecurityUi --> AiUi
  SecurityUi --> Files
  SecurityUi --> Notifications
  SecurityUi --> Search
  SecurityUi --> Collaboration
  SecurityUi --> Command
  WorkspaceUi --> Actions
  WorkspaceUi --> Contract
  WorkspaceUi --> Files
  WorkspaceUi --> Search
  WorkspaceUi --> Notifications
  WorkspaceUi --> Collaboration
  WorkspaceUi --> SecurityUi
  WorkspaceUi --> AiUi
  WorkspaceUi --> Command
  Activity --> Actions
  Activity --> Command
  Activity --> Contract
  Activity --> WorkspaceUi
  Activity --> Files
  Activity --> Search
  Activity --> Notifications
  Activity --> Collaboration
  Activity --> AiUi
  Activity --> SecurityUi
  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 graph          # Nx project graph
pnpm affected:quality
pnpm arch:check      # dependency-cruiser boundaries

Repo-wide tasks prefer pnpm nx run-many, pnpm nx affected, or pnpm nx run <project>:<target> 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
`prox-os.com`	`apps/os-shell`	Public landing, crawler-readable explanation layer
`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/apps/system-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/ui/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