OS Apps

Current Runtime

Reusable app implementations now live in category packages under packages/apps/*-apps. packages/apps/system-apps is reserved for OS-level apps such as App Store, App Map, System, Support, Trust Center, Governance, Notifications, ChatOS, and About. Personal, connector, developer, admin, game, founder, community, and hub apps live in their matching category packages.

apps/os-shell imports those packages through the registry and renderer bridge. It should behave like the runtime host rather than the container for every app implementation.

apps/os-shell still owns shell runtime behavior: routing, desktop grouping, iframe hosting, window manager state, shell settings, and control apps that directly affect the OS surface. Display options and Keyboard shortcuts remain local shell apps for now.

Package Ownership

• apps/os-shell: shell chrome, desktop, OS-level routing, local window manager, shell settings, iframe host, renderer adapter, and shell-coupled control apps.
• packages/apps/system-apps: reusable OS-level apps that can run from public app contracts, @prox-os/os-ui, and package-local code. Each app owns internal navigation; the shell must not assume how a window’s UI switches pages.
• packages/apps/user-apps: personal work, health, media, profile, workspace, and user-owned surfaces.
• packages/apps/user-connector-apps: mock connector shells and source-permission surfaces.
• packages/apps/dev-apps: developer tools, route map, and development workbench surfaces.
• packages/apps/admin-apps: admin, backend, deploy, and operations surfaces.
• packages/apps/game-apps: browser-native games and game collection surfaces.
• packages/apps/founder-apps: founder, pricing, roadmap, waitlist, and growth surfaces.
• packages/apps/community-apps: community and community admin surfaces.
• packages/apps/hub-apps: platform hub cockpit surfaces.
• packages/apps/app-shared: shared app primitives, manifest helpers, governance objects, life-record helpers, and proxied runtime UI.
• packages/runtime/app-registry: static iframe manifest templates for esmadrider-me and /app-dev localhost tools (see packages/runtime/app-registry/README.md). Consumed by the shell when composing registry.ts; must not import shell or os-apps implementations.
• packages/os-surface: shared Desktop Surface Engine model for layout modes, surface kinds, capabilities, placement shapes, and v0 capability overrides. It must not import shell state or app implementations.
• packages/contracts/app-contract: implementation-neutral manifest, window, permission, settings, keyboard, and runtime context types. Router-agnostic: no imports from @tanstack/react-router, react-router, next/router, or other concrete routers. Optional navigation hints on AppRuntimeContext describe generic intent only (navigationMode, initialPath, onNavigate, etc.), not router instances.

In-app routing (first-party vs third-party)

• Shell owns browser URL, window open/focus/close, and route groups (/app, /app-user, /app-connectors, /app-game, /app-hub, /app-os, …).
• First-party package apps may parse runtime.route.appPath for small deep links or mount TanStack Router for in-window structure, with a separate router instance per app (not the shell router). Prefer createMemoryHistory until an app explicitly needs browser-path deep links.
• Third-party or migrated apps may use React Router, Wouter, Next.js navigation, a small state machine, or no router. Prefer an adapter / wrapper to mount them behind the same manifest + runtime contract; do not force an internal rewrite just to land in Próx OS.
• Remote micro-frontends may share a React singleton when the integration model allows it; do not share a single Router instance across apps—history, base path, loaders, and URL state must stay scoped per app or host contract.
• Manifest routing uses routing.routeBase as the app launch base. The shell may extract appPath below that base, but it does not register app-owned internal pages.

Future adapter folders (incremental; not required for every stack):

packages/apps/system-apps/src/adapters/   # optional; add per integration as needed
  react-router/
  iframe/
  ...

Route split:

• /app/*: personal work, data, and creative apps.
• /app-edu/*: learning, study mode, practice labs, notes, reviews, and long-term personal growth surfaces.
• /app-health/*: health, sleep, dreams, body, mood, mindfulness, and sensitive personal tracking surfaces.
• /app-user/*: profile, visitor, preference, notification, shortcut, display, and user-specific surfaces.
• /app-connectors/*: personal connector apps for Alma summaries, Data Vault direction, Personal Knowledge Graph direction, and future MCP tools.
• /app-spaces/home: Proxied Space management for third-party web apps, compatibility, install destinations, and fallback settings. /app-spaces remains a root/folder route that should normalize to home.
• /app-spaces/slidepad: quick corner panel for Proxied Spaces and web-app rails.
• /app-game/*: browser-native games and future sandboxed game experiments.
• /app-shell/*: target group for shell-coupled apps that remain inside apps/os-shell.
• /app-admin/*: internal admin operations, growth, product intelligence, real OS data readiness, users, waitlist, feedback, audit, permissions, jobs, storage, and billing.
• /app-dev/*: local development tools, API docs, contracts, mock scenarios, Storybook, Scalar, architecture graphs, route maps, and debugging surfaces.
• /app-iframe/*: external and standalone Proxied Apps grouped under Proxied Apps; iframe is the current implementation detail.
• /app-os/*: reusable OS, official team, community, developer, and platform operations apps.
• /app-hub/*: productized vertical Hub cockpits with internal modules and bundle semantics.

/app-shell is still a target split. Current registered routes use /app, /app-edu, /app-health, /app-user, /app-connectors, /app-spaces, /app-game, /app-admin, /app-dev, /app-iframe, /app-os, and /app-hub.

Migrated Apps

The historical list below tracks the app migration wave that moved implementations out of apps/os-shell/src/apps. Package ownership has since been split by category; use the package ownership section above and the shell registry imports as the current source of truth for the owning package.

The migrated app implementation files have been removed from apps/os-shell/src/apps. New imports should use the owning category package root such as @prox-os/user-apps, @prox-os/game-apps, or @prox-os/os-apps. The shell keeps only runtime adapter files and the local shell control apps listed below.

Local Shell Apps

These apps stay inside apps/os-shell because they are tightly coupled to shell control behavior:

The shell also keeps packages/runtime/app-registry (iframe manifest data), iframe/IframeAppHost.tsx, AppRuntime.tsx, registry.ts, types.ts, and localAppComponents.tsx as runtime adapter code.

Package Structure

packages/apps/system-apps/
  package.json
  tsconfig.json
  src/
    index.ts
    shared/
      AppPrimitives.tsx
      defineOsAppManifest.ts
      governance*.ts
      mock-data.ts
    apps/
      core/
        app-store/
        architecture/
        chatos/
        monitor/
        ...
      growth/
        founder-suite/
        pricing/
        roadmap/
        ...
      media/
        games/
        moments/
        rss-knowledge-inbox/
        ...
      operations/
        admin/
        deploy/
        developer-tools/
        ...
      platform-suite/
        index.ts
        manifests.ts
        platformData.ts
        platformTypes.ts
        PlatformPrimitives.tsx
        <PlatformAppName>App.tsx
      user/
        user-connectors/
        user-profile/
        user-wallet/
        visitor/
      workspace/
        projects/
        ai-question-tracker/
        subscription-tracker/
        ...
      <category>/<app>/
        index.ts
        manifest.ts
        <AppName>App.tsx          # often wraps RouterProvider + app-local router
        <app>Router.tsx            # optional: createRoute tree + createRouter factory
        <app>Layout.tsx            # optional: nav + Outlet
        README.md optional

The long-term app package layout is category-based:

packages/apps/
  app-shared/
  system-apps/
  user-apps/
  user-connector-apps/
  dev-apps/
  admin-apps/
  game-apps/
  founder-apps/
  community-apps/
  hub-apps/

Every app owns its manifest next to the component. defineOsAppManifest stamps the standard runtime.kind: "os-package", routing.mode: "local-module", routing.owner: "app", and routing.preferredUrlMode: "path" metadata. The helper accepts sourcePackage so each app advertises the category package that owns it. Apps with multi-section UIs may express sections as app-owned routes (and optional search params) once they need deep links. Simple single-page apps can stay flat until they grow.

The apps/ directory is grouped by product responsibility rather than by registry route. core, operations, growth, workspace, media, platform-suite, and user are physical source folders only; app ids, manifests, route groups, App Store catalog entries, and shell renderer behavior remain registry-driven.

Some manifests use a stable product route that is shorter than the internal app id, such as os-about at /app-os/about and airtable-viewer at /app/airtable. Shell route parsing resolves these through registry routing.routeBase so the manifest remains the source of truth.

See app-routing.md for the Local Module App + Shell Wrapper route contract, including WindowInstance.route, AppRuntimeContext.route, iframe routing phases, and future external module direction.

The App Store is the exception where package-local catalog data can include roadmap and concept entries. That catalog must remain separate from the shell runtime registry so concept cards cannot imply that unregistered apps are launchable.

Styling Source Graph

The shell stylesheet must include all app category packages in its Tailwind source graph. Reusable app interiors rely on package-local utility classes, including arbitrary grid templates for split panes, dense tables, and piano-key style controls. If apps/os-shell/src/App.css stops scanning a category package, the components still render but their generated CSS disappears, so many apps collapse into single-column fallback layouts at once.

Boundaries

Category app packages may depend on:

• @prox-os/app-contract
• @prox-os/app-shared
• @prox-os/os-ui
• React peer dependencies
• package-local components, data, hooks, and utilities

It must not import:

• apps/os-shell/src/apps/*
• apps/os-shell/src/shell/*
• apps/os-shell/src/window-manager/*
• shell-private Zustand stores, settings implementations, shortcut handlers, or window-manager adapters

If an app needs shell facts, expose a readonly runtime snapshot or a narrow app-contract action first. Do not deep-import shell internals to make a migration pass.

API And State

Current app data is still local mock data or app-local arrays. No app in packages/apps/*-apps should perform direct remote fetching without an app-local API module and cache boundary.

Remote server data should move through app-local API modules and TanStack Query. Zustand remains for browser OS local state only. Shell runtime snapshots are intentionally readonly from the package app perspective.