Package Graph

Current Monorepo Shape

Próx OS is a pnpm workspace with apps and packages:

Packages are grouped by the taxonomy in package-taxonomy.md. Boundary enforcement is documented in package-boundaries.md.

Path	Package	Current role
`apps/os-shell`	`@prox-os/os-shell`	Main browser OS shell. Owns routes, composed app registry, local app runtime, windows, shell settings, desktop folders, and shell chrome.
`apps/esmadrider-me`	`@prox-os/esmadrider-me`	Static Vite founder site; Cloudflare Pages–oriented; registered as shell iframe app `esmadrider-me`. Must not import `apps/os-shell`.
`apps/api-worker`	`@prox-os/api-worker`	Cloudflare Worker skeleton using Hono. Exposes `/`, `/health`, `/openapi.json`, and Scalar docs at `/docs`.
`packages/ui/os-ui`	`@prox-os/os-ui`	Reusable React shell primitives and UI controls. Must stay free of shell state, app i18n, API fetching, and Zustand. Depends on `@prox-os/design-tokens` for CSS variables.
`packages/ui/design-tokens`	`@prox-os/design-tokens`	Shared `--os-*` CSS variables, optional Tailwind v4 `@theme` bridge, TypeScript `tokens` / `cssVars` helpers. No React; consumable by shell, `os-ui`, standalone apps, iframe bundles.
`packages/contracts/app-contract`	`@prox-os/app-contract`	Neutral contract package for app manifests, app runtime context, window instances, and permissions.
`packages/contracts/studio-contract`	`@prox-os/studio-contract`	Neutral Studio System contract package for Studio Engines, Studio Surfaces, Projection Surfaces, Projection Contracts, and `maxNestedInteractiveDepth`.
`packages/os-surface`	`@prox-os/os-surface`	Shared Studio surface capability model: layout modes, surface kinds, app surface capabilities, placement shapes, and v0 capability overrides.
`packages/ui/actions`	`@prox-os/actions`	Shared frontend action intent contract, helpers, and React primitives for context menus, toolbars, resource cards, command previews, and AI action previews.
`packages/ui/command`	`@prox-os/command`	Shared command contract, action bridge, provider types, ranking helpers, and React command palette primitives.
`packages/ui/forms`	`@prox-os/forms`	Shared form contract, validation adapters, field primitives, schema form renderer, and form action surface for app input/editing flows.
`packages/ui/editor`	`@prox-os/editor`	Shared editor contract, Tiptap/CodeMirror adapters, toolbar actions, status, preview, rich text, markdown, code, prompt, and comment primitives.
`packages/features/collaboration`	`@prox-os/collaboration`	Shared collaboration contracts and React primitives for participants, presence, comments, threads, mentions, sharing, review, approval, and resource collaboration panels.
`packages/ui/notifications`	`@prox-os/notifications`	Shared notification contracts and React primitives for badges, bells, toasts, notification center, digests, preferences, action refs, and notification adapter examples.
`packages/features/search`	`@prox-os/search`	Shared search contracts, local adapter, ranking/filter/facet helpers, result previews, saved searches, index stats, and OS-native search React primitives.
`packages/features/files`	`@prox-os/files`	Shared file/folder/storage contracts, file browser and picker primitives, preview models, transfer-state UI, and file adapter examples.
`packages/features/ai-ui`	`@prox-os/ai-ui`	Shared AI interaction contracts and React primitives for sessions, messages, runs, tool calls, approvals, artifacts, context sources, citations, model selection, usage, and risk.
`packages/features/security-ui`	`@prox-os/security-ui`	Shared security UI contracts and React primitives for principals, resources, permissions, risk, trust, sensitivity, policy notices, audit events, sessions, tokens, and reviews.
`packages/features/workspace-ui`	`@prox-os/workspace-ui`	Shared workspace UI contracts and React primitives for workspaces, spaces, members, roles, resources, projects, milestones, settings, onboarding, integrations, stats, and handoffs.
`packages/ui/activity`	`@prox-os/activity`	Shared activity timeline contracts and React primitives for actors, targets, objects, events, feeds, groups, digests, stats, redaction, related resources, and cross-domain adapters.
`packages/contracts/data-contract`	`@prox-os/data-contract`	Neutral contract package for structured datasets, fields, records, views, chart specs, source refs, permissions, and demo datasets. No React or UI.
`packages/features/data-table`	`@prox-os/data-table`	React table/grid primitives for OS-native data surfaces. Uses TanStack Table for normal business tables and Glide Data Grid as high-density grid evaluation.
`packages/features/data-viz`	`@prox-os/data-viz`	React chart primitives and adapters. Uses Apache ECharts by default, Vega-Lite for portable specs, and Recharts for simple dashboard cards.
`packages/features/media`	`@prox-os/media`	React media resource primitives for images, avatars, covers, embeds, external link previews, provider detection, allowlists, transforms, and future context action intent.
`packages/features/maps`	`@prox-os/maps`	React map/geospatial primitives for MapLibre previews, markers, layers, attribution, provider metadata, tile policy, and future context action intent.
`packages/runtime/app-registry`	`@prox-os/app-registry`	Proxied App registry templates (`esmadrider-me`, `/app-dev` localhost iframes today) + dev/prod URL resolution. Must not import `apps/os-shell`, `os-ui`, or `os-apps` source.
`packages/data/db`	`@prox-os/db`	Planned Drizzle + Neon package. Package exists; source files are currently empty placeholders.
`packages/backend/storage`	Not packaged yet	Planned S3-compatible storage abstraction. Source files are currently empty placeholders.
`packages/apps/system-apps`	`@prox-os/os-apps`	Reusable official OS apps imported by `apps/os-shell`. Most non-core app implementations now live here.

There is no packages/ui package in the current tree. The reusable UI package is packages/ui/os-ui.

Boundary Rules

Current dependency-cruiser config lives in .dependency-cruiser.js.

Important rules:

packages/ui/design-tokens must not import React, apps, os-ui, or os-apps (CSS + token TS only).
apps/esmadrider-me must not import apps/os-shell (standalone Pages app + iframe guest).
packages/ui/os-ui must not import apps/os-shell.
packages/ui/os-ui must not import Zustand, TanStack Query, or app i18n modules.
packages/contracts/app-contract must not import React, UI implementation code, or apps.
packages/contracts/studio-contract must not import React, UI implementation code, apps, database clients, or shell state.
packages/os-surface must not import apps/os-shell, UI packages, app implementations, database clients, or shell state. It is a shared runtime model, not a renderer.
packages/ui/actions may import React, but must not import OS Shell context menu internals, command palette internals, official app implementations, storage, or database code.
packages/ui/command may import @prox-os/actions, but must not import OS Shell command palette internals, official app implementations, storage, or database code.
packages/ui/forms may import React Hook Form, Zod, and @prox-os/actions, but must not import OS Shell form internals, official app implementations, storage, or database code.
packages/ui/editor may import Tiptap, CodeMirror, and @prox-os/actions, but must not import OS Shell editor internals, official app implementations, storage, or database code.
packages/features/collaboration may import React and @prox-os/actions, but must not import OS Shell runtime internals, official app implementations, realtime providers, storage, or database code.
packages/ui/notifications may import React, @prox-os/actions, and type-level collaboration adapters, but must not import OS Shell runtime internals, official app implementations, delivery providers, storage, database code, or push/realtime SDKs.
packages/features/search may import React, @prox-os/actions, @prox-os/command, @prox-os/collaboration, and @prox-os/notifications for adapter examples, but must not import OS Shell runtime internals, official app implementations, backend search providers, vector/embedding SDKs, storage, or database code.
packages/features/files may import React, @prox-os/actions, @prox-os/search, @prox-os/notifications, and @prox-os/collaboration for adapter examples, but must not import OS Shell runtime internals, official app implementations, real storage SDKs, browser file-system SDKs, upload backends, storage, or database code.
packages/features/ai-ui may import React, @prox-os/actions, @prox-os/editor, @prox-os/search, @prox-os/files, @prox-os/notifications, @prox-os/collaboration, and @prox-os/command for adapter examples, but must not import OS Shell runtime internals, official app implementations, real LLM SDKs, AI runtimes, MCP SDKs, streaming clients, vector/embedding SDKs, storage, or database code.
packages/features/security-ui may import React, @prox-os/actions, @prox-os/ai-ui, @prox-os/files, @prox-os/notifications, @prox-os/search, @prox-os/collaboration, and @prox-os/command for adapter examples, but must not import OS Shell runtime internals, official app implementations, auth providers, policy engines, KMS/secret tooling, scanner/SIEM SDKs, storage, or database code.
packages/features/workspace-ui may import React, @prox-os/actions, @prox-os/app-contract, @prox-os/files, @prox-os/search, @prox-os/notifications, @prox-os/collaboration, @prox-os/security-ui, @prox-os/ai-ui, and @prox-os/command for adapter examples, but must not import OS Shell runtime internals, official app implementations, auth providers, billing SDKs, workspace backends, project management engines, realtime providers, storage, or database code.
packages/ui/activity may import React, @prox-os/actions, @prox-os/command, @prox-os/app-contract, @prox-os/workspace-ui, @prox-os/files, @prox-os/search, @prox-os/notifications, @prox-os/collaboration, @prox-os/ai-ui, and @prox-os/security-ui for adapter examples, but must not import OS Shell runtime internals, official app implementations, analytics SDKs, telemetry SDKs, realtime providers, event stores, audit backends, storage, or database code.
packages/features/media may import React, but must not import OS Shell context menu internals, official app implementations, storage, or database code.
packages/features/maps may import React, MapLibre, and its React wrapper, but must not import OS Shell context menu internals, official app implementations, storage, database code, or geocoding/routing service implementations.
packages/runtime/app-registry must not import shell, UI, or os-apps implementations (static manifests + resolution only).
apps/os-shell/src/apps/** must not import apps/os-shell/src/shell/** internals; app-facing settings, keyboard, dialog, and window capabilities flow through @prox-os/app-contract, @prox-os/os-ui, app-local code, or explicit public adapters.
packages/apps/system-apps must not import apps/os-shell/src/apps/*, apps/os-shell/src/shell/*, or apps/os-shell/src/window-manager/*.
apps/os-shell may import packages.

Current App Package Flow

The first three app-boundary PRs established this flow:

packages/contracts/app-contract owns app manifests, runtime context, settings, keyboard, permission, and window contract types.
apps/os-shell owns shell runtime adapters: window manager, desktop, composed registry (merge app-registry + os-apps + shell-only entries), iframe host, and local renderer map.
packages/runtime/app-registry registers platform iframe templates (esmadrider-me under /app-iframe, dev tools under /app-dev). The shell currently exposes /app-dev iframe templates in all builds; production URLs still require the appropriate Access boundary.
packages/apps/system-apps now owns reusable official app code for most non-core apps. The shell imports package manifests into registry.ts and package components into the existing local renderer bridge.
apps/esmadrider-me is a standalone static app; it depends on design tokens, os-ui, and app-contract only—never apps/os-shell.

Allowed direction:

apps/os-shell -> packages/runtime/app-registry -> packages/contracts/app-contract
apps/os-shell -> packages/apps/system-apps -> packages/contracts/app-contract
apps/os-shell -> packages/apps/system-apps -> packages/ui/os-ui
apps/os-shell -> packages/ui/design-tokens
apps/ui-workshop -> packages/ui/actions
apps/ui-workshop -> packages/ui/command
apps/ui-workshop -> packages/ui/forms
apps/ui-workshop -> packages/ui/editor
apps/ui-workshop -> packages/features/collaboration
apps/ui-workshop -> packages/ui/notifications
apps/ui-workshop -> packages/features/search
apps/ui-workshop -> packages/features/files
apps/ui-workshop -> packages/features/ai-ui
apps/ui-workshop -> packages/features/security-ui
apps/ui-workshop -> packages/features/workspace-ui
apps/ui-workshop -> packages/ui/activity
apps/ui-workshop -> packages/contracts/data-contract
apps/ui-workshop -> packages/features/data-table
apps/ui-workshop -> packages/features/data-viz
apps/ui-workshop -> packages/features/media
apps/ui-workshop -> packages/features/maps
apps/esmadrider-me -> packages/ui/design-tokens
apps/esmadrider-me -> packages/ui/os-ui
apps/esmadrider-me -> packages/contracts/app-contract
packages/apps/system-apps -> packages/contracts/app-contract
packages/contracts/app-contract -> packages/os-surface
packages/os-surface -> packages/contracts/studio-contract
apps/os-shell -> packages/os-surface
apps/os-shell -> packages/contracts/studio-contract
apps/os-shell -> packages/ui/command
apps/os-shell -> packages/features/ai-ui
packages/apps/system-apps -> packages/ui/os-ui
packages/ui/command -> packages/contracts/studio-contract
packages/ui/command -> packages/ui/actions
packages/ui/forms -> packages/ui/actions
packages/ui/editor -> packages/ui/actions
packages/features/collaboration -> packages/ui/actions
packages/ui/notifications -> packages/ui/actions
packages/ui/notifications -> packages/features/collaboration
packages/features/search -> packages/ui/actions
packages/features/search -> packages/ui/command
packages/features/search -> packages/features/collaboration
packages/features/search -> packages/ui/notifications
packages/features/files -> packages/ui/actions
packages/features/files -> packages/features/search
packages/features/files -> packages/ui/notifications
packages/features/files -> packages/features/collaboration
packages/features/ai-ui -> packages/ui/actions
packages/features/ai-ui -> packages/ui/editor
packages/features/ai-ui -> packages/features/search
packages/features/ai-ui -> packages/features/files
packages/features/ai-ui -> packages/ui/notifications
packages/features/ai-ui -> packages/features/collaboration
packages/features/ai-ui -> packages/ui/command
packages/features/ai-ui -> packages/contracts/studio-contract
packages/features/security-ui -> packages/ui/actions
packages/features/security-ui -> packages/features/ai-ui
packages/features/security-ui -> packages/features/files
packages/features/security-ui -> packages/ui/notifications
packages/features/security-ui -> packages/features/search
packages/features/security-ui -> packages/features/collaboration
packages/features/security-ui -> packages/ui/command
packages/features/workspace-ui -> packages/ui/actions
packages/features/workspace-ui -> packages/contracts/app-contract
packages/features/workspace-ui -> packages/features/files
packages/features/workspace-ui -> packages/features/search
packages/features/workspace-ui -> packages/ui/notifications
packages/features/workspace-ui -> packages/features/collaboration
packages/features/workspace-ui -> packages/features/security-ui
packages/features/workspace-ui -> packages/features/ai-ui
packages/features/workspace-ui -> packages/ui/command
packages/ui/activity -> packages/ui/actions
packages/ui/activity -> packages/ui/command
packages/ui/activity -> packages/contracts/app-contract
packages/ui/activity -> packages/features/workspace-ui
packages/ui/activity -> packages/features/files
packages/ui/activity -> packages/features/search
packages/ui/activity -> packages/ui/notifications
packages/ui/activity -> packages/features/collaboration
packages/ui/activity -> packages/features/ai-ui
packages/ui/activity -> packages/features/security-ui
packages/features/data-table -> packages/contracts/data-contract
packages/features/data-viz -> packages/contracts/data-contract
packages/ui/os-ui -> packages/ui/design-tokens

Forbidden direction:

packages/runtime/app-registry -X-> apps/
packages/runtime/app-registry -X-> packages/ui/os-ui
packages/runtime/app-registry -X-> packages/apps/system-apps
packages/apps/system-apps -X-> apps/os-shell/src/apps
packages/apps/system-apps -X-> apps/os-shell/src/shell
packages/apps/system-apps -X-> apps/os-shell/src/window-manager
apps/esmadrider-me -X-> apps/os-shell

Shell runtime adapter files under apps/os-shell/src/apps/<app> may compose package apps during migration. Those files are adapters owned by the shell; they must not become implementation homes again.

Graph Types

Nx project graph and dependency-cruiser file graph answer different questions:

Nx project graph: package/project-level graph. Useful for workspace ownership and task boundaries.
dependency-cruiser file graph: source-file import graph. Useful for finding deep imports, accidental coupling, circular dependencies, and architecture rule violations.

Commands

Full command table: docs/platform/architecture/repo/arch-observability.md (Storybook remains pnpm dev:ui, not arch:all).

pnpm arch:project-graph   # interactive local server (port 4211)
pnpm docs:nx-graph        # static HTML export → apps/docs/public/tools/nx-graph (served at docs.prox-os.com/tools/nx-graph/)
pnpm arch:file-graph
pnpm arch:deps-dot
pnpm arch:check
pnpm arch:circular
pnpm arch:all          # static generators: symbols, hooks, graphs, TypeDoc JSON, Knip JSON, …
pnpm arch:ui           # alias → pnpm dev:ui (UI Workshop / Storybook)

Notes:

pnpm arch:project-graph runs nx graph and may open an interactive project graph.
pnpm docs:nx-graph exports a static project graph into the docs site (apps/docs/public/tools/nx-graph/). The docs prebuild runs this automatically; production OS Shell loads it via the nx-graph iframe prodIframeUrl.
pnpm arch:file-graph runs tsx scripts/arch/file-graph.ts: writes docs/platform/architecture/generated/file-graph.dot, renders generated/file-graph.svg when Graphviz dot exists, and copies to docs/platform/architecture/dependency-graph.svg for existing doc links.
pnpm arch:deps-dot writes docs/platform/architecture/deps.dot.
pnpm arch:check runs dependency-cruiser boundary checks.
pnpm arch:circular runs Madge circular dependency detection over apps and packages.

Generated Graph

Primary artifact:

docs/platform/architecture/generated/file-graph.svg (when dot is available).

Alternate graph export:

docs/platform/architecture/dependency-graph.svg

Regenerate with:

pnpm arch:file-graph

If SVG generation fails, install Graphviz so dot is on PATH (e.g. brew install graphviz on macOS). The .dot file is still written under docs/platform/architecture/generated/.