Core Architecture Thinking

This document is the **single engineering entry** for Próx OS runtime, build, state, visual, and UI-boundary philosophy. It links to topic documents that own de

Purpose

This document is the single engineering entry for Próx OS runtime, build, state, visual, and UI-boundary philosophy. It links to topic documents that own details. Read this first when onboarding, planning a refactor, or scoping AI agent work.

Status: Current (observation entry; code in apps/os-shell, packages/* remains authoritative).

Current Status

Area	Current	Planned / future
Shell build	Rsbuild + Rspack (`apps/os-shell`)	Module Federation–style splits are not wired yet
App hosts	`local-module`, `os-package`, `iframe`	`route-app`, `isolated-app` contract types exist; limited shell use
OS state	Zustand (`window-manager/store.ts`)	—
Remote data	TanStack Query provider mounted; no shell `useQuery` yet	API-backed registry, settings, notifications
Virtual desktops	Spaces in Zustand (`space-model.ts`)	Profile sync, cloud layout
Design system	`@prox-os/design-tokens` + `@prox-os/os-ui`	Dark mode tokens exist; more semantic roles over time

Reading Map

Question	Read
What is in the monorepo and how do I start it?	monorepo-workspace-guide.md
Rsbuild, React 18, app build freedom	build-and-rendering.md
Zustand vs Query vs localStorage	state-model.md
Windows, Spaces, Mission Control	window-manager.md
Boot, login, Hola	../ai/os-startup-flow.md
Tokens and Tailwind	../design/tokens.md
`os-ui` boundaries	../design/component-layering.md
Shell chrome visuals	../design/os-shell-design-language.md
App manifests and routes	app-registry.md, app-contract-view.md
Package import rules	package-graph.md, refactor-guardrails.md
AI doc routing	../ai/context-pack.md, ai-readable-index.md

Build and Rendering Pipeline (summary)

Próx OS Shell uses Rsbuild (Rspack) because the shell is a long-lived product surface that benefits from fast dev feedback, production bundling, and an ecosystem aligned with webpack-style tooling. Vite is used where a separate deployable app wants a minimal toolchain (apps/esmadrider-me). That split is intentional: shell build policy ≠ every app’s build policy.

See build-and-rendering.md for Rsbuild config paths, React 18 StrictMode expectations, and how iframe vs package apps relate to the shell bundle.

Runtime and App Integration (summary)

apps/os-shell (composed registry)
  ├── packages/app-registry   (iframe templates, URL resolution)
  ├── packages/os-apps      (official package apps)
  └── apps/os-shell/src/apps/* (local-module adapters, shell-only apps)

packages/app-contract       (manifest + runtime types, router-agnostic)

Launch path: registry manifest → openApp / router → AppRuntime → local renderer or iframe host. Cmd+K lists apps from appRegistry via shell/command/commandPaletteApps.ts (not desktop folder placement).

State Management Boundary (summary)

Zustand: browser OS mechanics — windows, Spaces, focus, command surface flags, Mission Control mode.
TanStack Query: remote async data and cache (provider ready; app usage still mostly mock/local).
localStorage: durable preferences and layout hints (proxOsLocalStorageKeys.ts).
React local state: ephemeral overlays, toasts, menus, animations.

Full field tables: state-model.md. Anti-pattern: caching API responses in Zustand or storing drag geometry in Query.

CSS and Visual Token Architecture (summary)

Semantic --os-* variables in @prox-os/design-tokens/css/prox.css are the stable visual contract. Tailwind should consume tokens (optional @prox-os/design-tokens/tailwind/theme.css), not ad-hoc hex in product code. Shell backgrounds use data-os-background, data-os-theme, data-os-density on <html>.

Details: ../design/tokens.md. Verification surface: apps/ui-workshop (Storybook).

Component Layering (summary)

packages/os-ui wraps presentational shell primitives (ShellBar, WindowFrame, CommandSurface, …). Headless libraries (Radix-style) belong behind os-ui, not in business apps. Apps and shell orchestration import @prox-os/os-ui + tokens; they do not own primitive accessibility plumbing.

Details: ../design/component-layering.md.

Backend Readiness

apps/api-worker (Hono on Cloudflare Workers) is the HTTP boundary. packages/db and remote reads are planned; see runtime-view.md, api-map.md, decisions/0003-msw-hono-openapi.md.

Documentation Governance

Canonical prose: root docs/ (English).
Site copy: apps/docs/content/docs via pnpm docs:sync.
Agents: AGENTS.md + docs/ai/context-pack.md; do not duplicate full architecture essays in chat-only notes.

Anti-Patterns

Consolidated list (also enforced in AGENTS.md and refactor-guardrails.md):

Do not copy the same architecture explanation into multiple docs — link instead.
Do not hard-code business colors in shell or apps when a semantic --os-* token exists.
Do not import Radix/Ariakit (or similar) directly from packages/os-apps or shell apps without an os-ui wrapper and an explicit exception.
Do not put server/cache payloads in Zustand.
Do not use TanStack Query for local window drag, Space geometry, or dock layout.
Do not let packages/os-ui import shell stores, app registry, TanStack Query, or API clients.
Do not move complexity into another 500+ line file — split by responsibility.
Do not document Module Federation, qiankun, or remote registry sync as shipped unless the code proves it.
Do not add docs only under docs/ without running pnpm docs:sync when the docs site must show them.

Decision Records

Decision: Rsbuild/Rspack for the OS Shell

Status: Accepted (current)

Context: The shell is the primary long-session UI; dev speed and production bundling matter more than sharing Vite with every satellite app.

Decision: apps/os-shell builds with Rsbuild (rsbuild.config.ts). Other deployables may use Vite or other tools when isolated.

Consequences: Shell-specific plugins (e.g. React Compiler via Babel) live in the shell config. Shared packages ship as TypeScript source consumed by the bundler.

Anti-patterns: Forcing all future apps onto Rsbuild without a boundary reason; importing shell internals from iframe children.

Related files: apps/os-shell/rsbuild.config.ts, build-and-rendering.md

Decision: React 18 StrictMode in development

Status: Accepted (current)

Context: apps/os-shell/src/index.tsx mounts under <React.StrictMode>.

Decision: Treat double-invoked effects in development as a signal to write idempotent setup/teardown (listeners, timers, store hydration), not as a reason to disable StrictMode casually.

Consequences: Boot and persistence code must tolerate dev remounts; production runs a single mount.

Related files: apps/os-shell/src/index.tsx, browser-local/applyBootShellAppearance.ts

Decision: Zustand for local OS state

Status: Accepted (current)

Decision: Window/Space/Mission Control/command flags live in apps/os-shell/src/window-manager/store.ts.

Consequences: Redux DevTools middleware may be used for debugging transitions. Remote data stays out of this store.

Related files: state-model.md, window-manager.md

Decision: TanStack Query for remote async state

Status: Accepted (provider mounted; data layer planned)

Decision: Server reads/writes use Query at app or shell API boundaries, not Zustand.

Related files: apps/os-shell/src/providers/QueryProvider.tsx, decisions/0003-msw-hono-openapi.md

Decision: Semantic design tokens before raw colors

Status: Accepted (current)

Decision: @prox-os/design-tokens owns --os-*; apps consume variables or Tailwind bridge utilities.

Related files: packages/design-tokens/css/prox.css, ../design/tokens.md

Decision: `os-ui` as the UI primitive boundary

Status: Accepted (current)

Decision: Shared visual/interaction primitives live in packages/os-ui without business state or data fetching.

Related files: packages/os-ui/src/index.ts, ../design/component-layering.md

Decision: Docs-first, AI-readable observatory

Status: Accepted (current)

Decision: Architecture behavior is summarized under docs/architecture/* with generated graphs via pnpm arch:* where applicable.

Related files: arch-observability.md, ai-readable-index.md

ADR	Topic
0001-local-module-apps.md	Local module apps as default host
0002-window-instance-routing.md	Global routes vs per-window app routes
0003-msw-hono-openapi.md	API worker, OpenAPI, Scalar, MSW direction

README.md — architecture section index
../design/DESIGN.md — design constitution
../ai/os-startup-flow.md — shell boot sequence

Core Architecture Thinking

On this page