PlatformArchitectureRepo
Package Taxonomy
Prox OS uses package names to describe product domains and directory layers to
Prox OS uses package names to describe product domains and directory layers to
describe runtime and ownership boundaries. Package names stay stable, for
example @prox-os/forms or @prox-os/app-contract; their filesystem location
shows whether the package is UI, feature, contract, runtime, data, backend,
devtooling, or an app package.
This avoids prefixes such as fe- and be-. A package named
@prox-os/files should stay domain-readable even if its implementation later
gains a backend adapter package. The directory, Nx tags, proxos metadata, and
dependency-cruiser rules carry the runtime boundary.
Layers
| Layer | Directory | Responsibility | May depend on | Must not depend on |
|---|---|---|---|---|
| UI | packages/ui/* | Reusable browser UI primitives and interaction contracts. | contracts, safe UI peers, design tokens, documented browser-safe feature adapters. | backend, server data packages, provider SDKs, shell internals. |
| Features | packages/features/* | Browser-safe feature packages such as files, search, AI UI, workspace UI, maps, media, tables, and charts. | ui, contracts, other browser-safe features when documented. | backend, DB clients, runtime shell internals. |
| Contracts | packages/contracts/* | Shared serializable types, manifests, schemas, API/event contracts. | Minimal external type utilities. | ui, features, runtime, backend, browser-only or server-only implementation. |
| Runtime | packages/runtime/* | OS runtime registries, app/window/workspace runtime helpers, and manifest resolution. | contracts, selected ui types when safe. | backend by default, feature implementation unless explicitly documented. |
| Studio Engines | packages/studio-engines/* | Browser Studio Engine implementations with renderer-specific dependencies. | contracts, command types, browser-safe UI, engine-owned deps. | Shell internals, backend, user Studio instances. |
| Data | packages/data/* | Data schemas, query clients, fixtures, mock data, and DB-facing packages. | contracts, backend-safe utilities. | Browser packages when the package contains server-only clients. |
| Backend | packages/backend/* | Server-only packages such as auth, billing, storage, audit, moderation, AI adapters, and worker shared code. | contracts, data, server-safe tooling. | Browser UI/features/apps. |
| Devtools | packages/devtools/* | Repo tooling, generators, lint/tsconfig/test/storybook helpers. | contracts, tooling deps. | Product runtime packages unless tooling-specific. |
| App Packages | packages/apps/* | Importable OS app bundles registered by the shell, not deployable apps. | contracts, ui, browser-safe features. | Shell private internals, backend packages, deployable app code. |
Current Package Placement
| Package | Path | Layer | Runtime |
|---|---|---|---|
@prox-os/actions | packages/ui/actions | UI | browser |
@prox-os/activity | packages/ui/activity | UI | browser |
@prox-os/command | packages/ui/command | UI | browser |
@prox-os/design-tokens | packages/ui/design-tokens | UI | shared |
@prox-os/editor | packages/ui/editor | UI | browser |
@prox-os/forms | packages/ui/forms | UI | browser |
@prox-os/notifications | packages/ui/notifications | UI | browser |
@prox-os/os-ui | packages/ui/os-ui | UI | browser |
@prox-os/ai-ui | packages/features/ai-ui | Feature | browser |
@prox-os/collaboration | packages/features/collaboration | Feature | browser |
@prox-os/data-table | packages/features/data-table | Feature | browser |
@prox-os/data-viz | packages/features/data-viz | Feature | browser |
@prox-os/files | packages/features/files | Feature | browser |
@prox-os/maps | packages/features/maps | Feature | browser |
@prox-os/media | packages/features/media | Feature | browser |
@prox-os/search | packages/features/search | Feature | browser |
@prox-os/security-ui | packages/features/security-ui | Feature | browser |
@prox-os/workspace-ui | packages/features/workspace-ui | Feature | browser |
@prox-os/alma | packages/features/alma | Feature | browser |
@prox-os/inspector | packages/features/inspector | Feature | browser |
@prox-os/platform-navigation | packages/features/platform-navigation | Feature | browser |
@prox-os/app-contract | packages/contracts/app-contract | Contract | shared |
@prox-os/data-contract | packages/contracts/data-contract | Contract | shared |
@prox-os/studio-contract | packages/contracts/studio-contract | Contract | shared |
@prox-os/app-registry | packages/runtime/app-registry | Runtime | shared |
@prox-os/os-runtime | packages/runtime/os-runtime | Runtime | shared |
@prox-os/runtime-chrome | packages/runtime/runtime-chrome | Runtime | browser |
@prox-os/studio-registry | packages/runtime/studio-registry | Runtime | browser |
@prox-os/block-studio-engine | packages/studio-engines/block | Studio Engine | browser |
@prox-os/board-studio-engine | packages/studio-engines/board | Studio Engine | browser |
@prox-os/flow-studio-engine | packages/studio-engines/flow | Studio Engine | browser |
@prox-os/connectors | packages/connectors | Runtime | shared |
@prox-os/embed-runtime | packages/embed-runtime | Runtime | shared |
@prox-os/db | packages/data/db | Data | server |
@prox-os/app-shared | packages/apps/app-shared | App package | browser |
@prox-os/os-apps | packages/apps/system-apps | App package | browser |
@prox-os/user-apps | packages/apps/user-apps | App package | browser |
@prox-os/user-connector-apps | packages/apps/user-connector-apps | App package | browser |
@prox-os/dev-apps | packages/apps/dev-apps | App package | browser |
@prox-os/admin-apps | packages/apps/admin-apps | App package | browser |
@prox-os/game-apps | packages/apps/game-apps | App package | browser |
@prox-os/founder-apps | packages/apps/founder-apps | App package | browser |
@prox-os/community-apps | packages/apps/community-apps | App package | browser |
@prox-os/hub-apps | packages/apps/hub-apps | App package | browser |
packages/backend/storage is currently source-only placeholder code, not a
workspace package yet. It sits in the backend layer because object storage
presigning and provider bindings are server concerns.
packages/connectors and packages/embed-runtime are lightweight App Hub
aggregation packages. They are root-level workspace packages by design for the
early App Hub phase and should stay limited to types, mock data, and safe
helpers until a real runtime layer split is justified.
Choosing A Directory For A New Package
- Decide whether the package is importable by browser code.
- Decide whether it owns a product domain, a reusable primitive, a runtime bridge, a contract, or a server implementation.
- Pick the layer before picking a package name.
- Add
nx.tagsandproxosmetadata to the package manifest. - Add dependency-cruiser rules or exceptions if the package introduces a new kind of boundary.
- Update the architecture document that owns the boundary.
Future Package Examples
| Future package | Suggested path | Reason |
|---|---|---|
@prox-os/api-contract | packages/contracts/api-contract | Shared API request/response contract. |
@prox-os/event-contracts | packages/contracts/event-contracts | Shared event and activity payload shapes. |
@prox-os/app-runtime | packages/runtime/app-runtime | Future app-specific runtime bridge if it stays separate from @prox-os/os-runtime. |
@prox-os/query-client | packages/data/query-client | Browser query utilities without DB clients. |
@prox-os/auth | packages/backend/auth | Server-only authentication implementation. |
@prox-os/billing | packages/backend/billing | Server-only billing implementation. |
@prox-os/ai-core | packages/backend/ai-core | Backend AI orchestration boundary. |
@prox-os/storybook-utils | packages/devtools/storybook-utils | Shared Storybook tooling. |
@prox-os/os-studio-engine | packages/studio-engines/os | Future extraction only when Shell coupling is reduced. |
AI Agent Checklist
Before creating a package, an agent should answer:
- What layer owns this responsibility?
- Is the runtime
browser,server,shared, ortooling? - Which scopes apply:
os,admin,founder,workspace,ai, ordata? - Which packages may import it?
- Which packages must never import it?
- Does it need a contract package first?
- Does the change require a dependency-cruiser rule or architecture note?
If those answers are unclear, prefer a small contract package or a focused feature package over a broad implementation package.