Nx Project Graph

Purpose

The Nx project graph is the repo-level map for Prox OS. It complements dependency-cruiser, generated architecture reports, and package-boundary docs.

Nx answers:

which projects exist;
which targets are available;
which packages a change can affect;
which build, lint, or typecheck tasks can be cached;
which projects should be validated by an AI-assisted branch.

Project Families

Deployable apps: @prox-os/os-shell, @prox-os/api-worker, @prox-os/docs, @prox-os/ui-workshop, @prox-os/esmadrider-me.
Contracts and runtime packages: @prox-os/app-contract, @prox-os/data-contract, @prox-os/app-registry, @prox-os/os-surface.
UI and feature packages: @prox-os/os-ui, design tokens, actions, command, forms, editor, AI UI, files, search, workspace, security, activity, media, maps, data table, and data visualization packages.
Official OS apps: @prox-os/os-apps.
Data and backend packages: database and storage boundaries.

Inputs

nx.json uses named inputs:

default: project files plus shared globals.
production: default minus stories and tests.
sharedGlobals: repo-level config, lockfile, AGENTS, and AI context docs.
docs: canonical documentation inputs.

The shared globals make architectural and AI-facing rule changes visible to Nx task hashing.

Target Defaults

Key target defaults:

build depends on upstream builds and uses production inputs.
typecheck and lint depend on upstream equivalents and use project inputs.
test is cacheable when a project has a real test target.
dev, serve, preview, and storybook are not cached.
deploy depends on the project build and is never cached.
database mutation targets are intentionally not cached.

Relationship With Architecture Gates

Nx does not replace all architecture tools. Prox OS still uses:

dependency-cruiser through pnpm arch:check;
large-file checks through pnpm check:file-size;
CJK policy checks through pnpm check:cjk;
generated architecture reports through pnpm arch:*.

Nx chooses and runs project tasks. The architecture tools enforce boundaries and produce human/AI-readable reports.

Future Boundary Tags

Future Nx tags should encode package taxonomy:

scope:shell
scope:apps
scope:contracts
scope:runtime
scope:ui
scope:features
scope:data
scope:backend

Those tags can eventually prevent official app packages from deep-importing shell internals and prevent pure UI packages from importing business state.