App Routing Architecture

Scope

This document defines the app-level routing contract for Prox OS apps hosted by the shell.

It does not redesign OS-level routing. Runtime route groups such as /app, /app-edu, /app-health, /app-user, /app-connectors, /app-game, /app-admin, /app-dev, /app-iframe, /app-os, and /app-hub stay registry-driven. Future owner-scoped paths such as /@esmadrider/apps/waitlist-pro and Store listing paths stay governed by url-and-surface-model.md and app-namespace-and-domain-strategy.md.

The short rule:

Shell owns app discovery.
App owns internal route.
Shell Wrapper passes route context.
Manifest declares the routing boundary.

Route Layers

The shell may parse a URL prefix to find the registered app, but it must not register every app's internal pages. For example, /app/dreams/entry/rem-city can open the Dreams app and pass appPath: "/entry/rem-city"; the shell does not need to know what entry/rem-city means.

Local Module App + Shell Wrapper

Local Module Apps are the current default for fast OS app incubation:

apps/os-shell/src/apps/AppRuntime.tsx is the current Shell Wrapper. It stays thin:

It does not:

Manifest Routing Metadata

Current manifests use routing as the single launch and app-route boundary field:

export type AppRoutingConfig = {
  mode: 'local-module' | 'iframe' | 'external-module' | 'web-component' | 'remote-route' | 'system'
  owner: 'shell' | 'app'
  routeBase: `/${string}`
  defaultPath?: `/${string}`
  supportsDeepLink?: boolean
  preferredUrlMode?: 'path' | 'hash' | 'query' | 'memory'
  externalEntry?: string
  healthPath?: string
  allowedOrigins?: string[]
}

routeBase replaces the older top-level routePath manifest field. It is the canonical runtime launch base. It may differ from the internal appId, such as airtable-viewer at /app/airtable or os-about at /app-os/about.

Recommended defaults:

Runtime Route Context

Apps receive a router-agnostic route context:

export type AppRuntimeRoute = {
  appId: string
  routeBase: `/${string}`
  appPath: `/${string}`
  fullPath: string
  windowId?: string
  params?: Record<string, string>
  search?: string
  hash?: string
}

Current helpers in @prox-os/app-contract:

Current shell adapter points:

Current Route Schema

The current project does not have a stable public manifest API yet, so this contract chooses a clear current schema instead of parallel route fields.

Migration rules:

App Incubation Guidance

Fast UI incubation does not require a full internal router on day one.

Use the lightest route model that fits:

Examples:

/app/dreams
/app/dreams/entry/:id
/app/dreams/symbols
/app-game
/app-game/snake
/app-os/badges/github-star

These are app-level examples under current runtime route groups. They do not replace future owner-scoped paths such as /@esmadrider/apps/xxx.

Phase 2: Local App Internal Routing

Phase 2 keeps local apps in the bundle but lets them opt into deep links:

Phase 3: Iframe App Routing Protocol

Iframe apps are the preferred early external app boundary because they isolate runtime, dependencies, CSS, and app-owned routing while letting the OS ecosystem grow quickly.

Future shell-to-iframe message:

INIT { appId, routeBase, initialPath, theme, locale, windowId, capabilities }

Future iframe-to-shell messages:

READY {}
NAVIGATE { path, replace? }
TITLE_CHANGE { title }
REQUEST_OPEN_APP { appId, path? }
REQUEST_EXTERNAL_OPEN { url }
ERROR { message }

Iframe URL modes:

path:  https://example.com/prox/entry/123
hash:  https://example.com/#/entry/123
query: https://example.com?proxPath=/entry/123

routing.preferredUrlMode declares the preferred bridge style. The current shell documents the direction but does not yet implement the full postMessage route protocol.

Phase 4: External Module And Micro Frontend Routing

External Module Apps are a later integration tier, not the current default.

The invariant remains:

Active route and routeBase let the shell discover and mount the app.
Internal route belongs to the external app.
Capabilities flow through runtime context or a bridge.

Do not add those runtimes until the product has a concrete app that needs them.

Non-goals

Acceptance Checklist