Architecture
docs/platform/architecture is the living architecture observatory for Prox OS. It gives humans and AI agents a fast map of the current Web OS without requiring
docs/platform/architecture is the living architecture observatory for Prox OS. It gives humans and AI agents a fast map of the current Web OS without requiring a full source read on every task.
The source code remains the source of truth. These documents are observation entries: they summarize what the code currently does, mark planned work explicitly, and point back to the files that own behavior.
Reading Order
Start with the smallest path that matches the task.
| Need | Start here | Notes |
|---|---|---|
| Product and architecture baseline | overview/core-architecture-thinking.md | Engineering hub for runtime, state, tokens, boundaries, and anti-patterns. |
| Workspace and package map | repo/monorepo-workspace-guide.md | Apps, packages, commands, and shell source map. |
| Browser OS runtime | runtime/runtime-first-platform.md | Runtime posture before app-specific or package-specific details. |
| Shell chrome, shortcuts, and Cmd+K | shell/command-palette.md | Pair with shell/command-surface-competitive-analysis.md for Raycast-class positioning. |
| App registry and route groups | apps/app-registry.md | Manifest-driven app launch, registry facts, and app ownership. |
| Spaces and window layout | spaces/space-desktop-window-session.md | Space, desktop, window, and layout-preset boundaries. |
| Alma and AI surfaces | ai/alma-control-plane.md | Alma, Cmd+K, AI Entry, Slash Menu, approval, and audit posture. |
| Data, connectors, and backend | data/data-flow.md | State, data, API, connector, and personal data boundaries. |
| Reusable capability packages | capabilities/actions.md | Actions, forms, search, notifications, files, collaboration, activity, and security UI. |
| Media and collaborative references | media/media-and-images.md | Images, maps, charts, presence, multiplayer, and media resource posture. |
| Routes and owner-scoped URLs | routing/url-and-surface-model.md | Surface URLs, resources, route intelligence, and system context. |
| Architecture observability | repo/arch-observability.md | pnpm arch:*, generated reports, graph facts, and check boundaries. |
| Regional feature posture | regional/region-and-feature-profiles.md | Global, regional, and feature profile boundaries. |
| Accepted decisions | decisions/ | ADRs for local modules, window instance routing, and MSW/Hono/OpenAPI. |
Directory Map
| Directory | Owns | Typical task |
|---|---|---|
overview/ | High-level architecture vocabulary and product-runtime frame. | Re-anchor before cross-domain changes. |
repo/ | Monorepo structure, package boundaries, build/rendering, generated reports, and refactor guardrails. | Package moves, graph checks, build changes. |
runtime/ | Browser OS runtime, proxied app runtime, live runtime, desktop route model, and public Shell layer. | Runtime host, route entry, iframe/proxied app changes. |
shell/ | Cmd+K, command contracts, shortcuts, window manager, launchpad, display options, overlays, and i18n boundary. | Shell chrome, command surface, keyboard, window behavior. |
apps/ | App manifests, route taxonomy, registry, app map, store/library surfaces, and OS app ownership. | New app registration, route group changes, App Store metadata. |
spaces/ | Spaces, desktop grid, window sessions, layout presets, widgets, and workspace-Alma geometry. | Space, desktop, window layout, and responsive grid work. |
ai/ | Alma, AI UI, Studio system, prompt studio, app builder, and multi-agent workspace concepts. | AI surface, Studio, prompt, approval, and agent visibility changes. |
data/ | API map, backend foundation, connectors, state model, personal data, and structured data integrations. | Data flow, connector, API, state ownership, and backend boundary work. |
capabilities/ | Shared capability systems such as actions, forms, editor, files, search, activity, and security UI. | Reusable package contracts and package-level UI primitives. |
media/ | Charts, maps, media resources, images, presence, and multiplayer references. | Rich media and collaborative surface work. |
routing/ | Surface URLs, resource URLs, route intelligence, and system context. | URL model and route-resource architecture work. |
regional/ | Region and feature profile architecture. | Availability, regional posture, and feature profile discussions. |
operations/ | Deployment access and client/OS roadmap notes that still touch architecture. | Cloudflare access, client distribution, and OS roadmap boundaries. |
decisions/ | Accepted architecture decisions. | Decision lookup and ADR follow-up. |
Product Cross-links
| Need | Document |
|---|---|
| Platform vision and object model | ../../product/strategy/prox-os-platform-vision.md |
| Product positioning | ../../product/strategy/prox-os-positioning.md |
| Competitive landscape | ../../product/strategy/competitive-landscape.md |
| UI app competitor matrix | ../../product/apps/matrix/ui-app-competitive-matrix.md |
| Platform app prototypes | ../../product/strategy/platform-core-app-prototypes.md |
| Device Studio and client roadmap | ../../product/clients/device-studio/README.md |
Maintenance Rule
When code changes alter package boundaries, app registration, window semantics, shell state ownership, data flow, API routes, command behavior, or Space semantics, update the relevant architecture subdirectory in the same change.
When code changes alter product positioning, App Store collections, platform capability models, user segments, commercialization, or growth loops, update docs/product/*, docs/business/*, or docs/go-to-market/* instead of placing product strategy inside architecture.