Architecture Observatory

docs/architecture is the living code observatory for Próx 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

1. README.md - start here for the document map.
2. core-architecture-thinking.md - engineering hub: build, state, tokens, UI boundaries, anti-patterns, decision summaries.
3. monorepo-workspace-guide.md - apps/packages catalog, dev commands, shell source map.
4. cloudflare-deploy-and-access.md - deployment targets, custom domains, Access boundaries, API docs exposure, MCP safety.
5. arch-observability.md - pnpm arch:* generators: what runs, what is heuristic vs sourced, Knip rules.
6. package-graph.md - understand the monorepo packages and graph commands.
7. build-and-rendering.md - Rsbuild/Rspack shell build, React 18 StrictMode, app build freedom.
8. app-registry.md - see how apps are registered and launched.
9. window-manager.md - windows, Spaces (virtual desktops), Mission Control.
10. state-model.md - Zustand vs TanStack Query vs localStorage (field tables).
11. data-flow.md - follow the click-to-render flow and planned API path.
12. api-map.md - inspect current API surface and planned shell endpoints.
13. os-apps.md - review bundled apps and future extraction candidates.
14. decisions/* - architecture decision records (local modules, routing, API stack).

Document Map

• core-architecture-thinking.md: single entry for runtime/design/state philosophy and consolidated anti-patterns.
• monorepo-workspace-guide.md: workspace apps/packages, startup commands, production domain direction.
• cloudflare-deploy-and-access.md: Cloudflare deploy targets, custom domains, Access boundaries, API docs exposure, MCP safety, and manual dashboard follow-up.
• build-and-rendering.md: Rsbuild shell pipeline and React 18 expectations.
• ../product/prox-os-positioning.md: product positioning and cloud-first wedge.
• ../product/app-store-collections.md: App Store collection model, Space direction, and collection-to-platform mapping.
• ../product/platform-capabilities.md: eight reusable platform capability layers.
• arch-observability.md: architecture observability pipeline (pnpm arch:*), generated outputs under generated/, Knip governance, Storybook vs arch:all.
• package-graph.md: workspace structure, package responsibilities, graph tooling, and boundary checks.
• generated/file-graph.svg (and dependency-graph.svg legacy copy): dependency-cruiser file graph when Graphviz dot is available.
• app-registry.md: app manifest facts, route groups, runtime mapping, and future manifest shape.
• window-manager.md: current window instance model and shell/window-manager boundaries.
• state-model.md: state ownership by Zustand, TanStack Query, localStorage, and React local state.
• data-flow.md: Mermaid data-flow diagram from shell action to app rendering and future API reads.
• api-map.md: current Hono routes, shell mocks, and planned API endpoints.
• os-apps.md: app inventory, ownership, route groups, current state, and extraction guidance.
• decisions/0001-local-module-apps.md: why Local Module Apps are the current default.
• decisions/0002-window-instance-routing.md: how global routes and future per-window app routes should relate.
• decisions/0003-msw-hono-openapi.md: why MSW, Hono, OpenAPI, and Scalar are the planned API path.

Maintenance Rule

When code changes alter package boundaries, app registration, window semantics, shell state ownership, or API routes, update the relevant document in the same change.

When code changes alter product positioning, App Store collections, platform capability models, Spaces, or growth loops, update docs/product/* or the focused roadmap files under docs/roadmap/* in the same change.