Package Graph

Current Monorepo Shape

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

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/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/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/app-contract`	`@prox-os/app-contract`	Neutral contract package for app manifests, app runtime context, window instances, and permissions.
`packages/app-registry`	`@prox-os/app-registry`	Platform iframe registry templates (`esmadrider-me`, `/app-dev` localhost iframes) + dev/prod URL resolution. Must not import `apps/os-shell`, `os-ui`, or `os-apps` source.
`packages/db`	`@prox-os/db`	Planned Drizzle + Neon package. Package exists; source files are currently empty placeholders.
`packages/storage`	Not packaged yet	Planned S3-compatible storage abstraction. Source files are currently empty placeholders.
`packages/os-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/os-ui.

Boundary Rules

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

Important rules:

packages/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/os-ui must not import apps/os-shell.
packages/os-ui must not import Zustand, TanStack Query, or app i18n modules.
packages/app-contract must not import React, UI implementation code, or apps.
packages/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/os-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/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/app-registry registers platform iframe templates (esmadrider-me under /app-iframe, dev tools under /app-dev). Production builds omit devOnly entries when the shell merges (see registry.ts).
packages/os-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/app-registry -> packages/app-contract
apps/os-shell -> packages/os-apps -> packages/app-contract
apps/os-shell -> packages/os-apps -> packages/os-ui
apps/os-shell -> packages/design-tokens
apps/esmadrider-me -> packages/design-tokens
apps/esmadrider-me -> packages/os-ui
apps/esmadrider-me -> packages/app-contract
packages/os-apps -> packages/app-contract
packages/os-apps -> packages/os-ui
packages/os-ui -> packages/design-tokens

Forbidden direction:

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

Shell compatibility files under apps/os-shell/src/apps/<app> may re-export 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/architecture/arch-observability.md (Storybook remains pnpm dev:ui, not arch:all).

pnpm arch:project-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 arch:file-graph runs tsx scripts/arch/file-graph.ts: writes docs/architecture/generated/file-graph.dot, renders generated/file-graph.svg when Graphviz dot exists, and copies to docs/architecture/dependency-graph.svg for existing doc links.
pnpm arch:deps-dot writes docs/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/architecture/generated/file-graph.svg (when dot is available).

Legacy copy for older links:

docs/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/architecture/generated/.