ADR 0001: Local Module Apps First
Accepted.
Status
Accepted.
Context
Próx OS is still building the browser OS shell: desktop folders, app registry, window manager, shellbar, command surface, settings, and route/view modes.
The first shell milestone started with Local Module Apps in apps/os-shell/src/apps, registered through apps/os-shell/src/apps/registry.ts, and rendered through AppRuntime.tsx.
After the app contract, iframe runtime, and app extraction PRs, most non-core apps are now OS Package Apps exported from @prox-os/os-apps. Shell-coupled control apps such as Display options and Keyboard shortcuts remain local modules.
Decision
Keep shell-coupled control surfaces as Local Module Apps until their app contracts are stable. Allow reusable official apps to move to packages/os-apps when they can use public contracts, package-local code, and @prox-os/os-ui without shell-private imports.
Why Not Micro-Frontends Yet
Starting with micro-frontends would add deployment, versioning, sandboxing, routing, shared dependency, and permission complexity before the OS shell contract is stable.
The current risks are product shape and shell semantics, not independent app deployment.
Consequences
Benefits:
- Fast iteration on shell and app UX.
- One registry shape for all app classes.
- Easy refactors while route groups and window semantics are changing.
- No premature module federation or iframe boundary.
Costs:
- Bundle can grow as apps accumulate.
- App isolation is conceptual, not runtime-enforced.
- App teams cannot deploy independently yet.
Migration Conditions
Move an app toward packages/os-apps when:
- its manifest fields are stable
- it uses public app contracts instead of shell internals
- it has typed API/data dependencies
- it can be tested independently
- bundle size or ownership pressure justifies extraction
Even then, OS Package Apps are introduced as an incremental bridge, not as a micro-frontend or independent deployment boundary. Compatibility re-exports under apps/os-shell/src/apps/<app> are temporary adapters and should not grow new implementation code.