Prox OS Docs
Architecture

Architecture observability (`pnpm arch:*`)

This repository treats **architecture as an observability surface**: reports and diagrams are generated from **source**, **workspace layout**, **TypeScript AST*

This repository treats architecture as an observability surface: reports and diagrams are generated from source, workspace layout, TypeScript AST, TypeDoc, dependency-cruiser, and seed configs — not from hand-drawn diagrams or unverifiable AI prose.

Why this exists

  • Index, don’t replace, reading code. The goal is to answer “where is the hub?”, “which hook is heavy?”, “how do props flow?”, and “what does the app contract expose?” without opening every file.
  • Honest uncertainty. Outputs marked heuristic, seed, or needs manual review are approximations. They must not be treated as ground truth without verification.

What arch:all does and does not do

  • pnpm arch:all runs one-shot generators (CLI completes). It does not start dev servers.
  • UI / Storybook for visual component work: use pnpm dev:ui (same as @prox-os/ui-workshop Storybook). Optional alias: pnpm arch:ui → pnpm dev:ui. Storybook is intentionally not part of arch:all.

Command reference

CommandOutput / behavior
pnpm arch:file-graphdocs/architecture/generated/file-graph.dot; file-graph.svg if Graphviz dot is installed; copies to docs/architecture/dependency-graph.svg when SVG succeeds
pnpm arch:code-symbolsgenerated/code-symbols.{md,json} — per-file exports, hooks, types, imports (ts-morph)
pnpm arch:hook-complexitygenerated/hook-complexity.md — metrics for use*.ts(x)
pnpm arch:props-flowgenerated/props-flow.{md,mmd} (+ optional .svg) — static JSX approximation
pnpm arch:c4generated/c4-container.{mmd} (+ optional .svg) — workspace discovery + scripts/arch/c4-external.seed.json for external systems
pnpm arch:stategenerated/state-ownership.{md,mmd} (+ optional .svg) — regex/pattern buckets (manual review)
pnpm arch:capabilitiesgenerated/app-capabilities.{md,mmd} — contract vs forbidden shell imports in packages/os-apps
pnpm arch:apiTypeDoc HTML → generated/api/ (entry: packages/app-contract/src/index.ts, options: root typedoc.json)
pnpm arch:api:jsonTypeDoc JSON → generated/api.json
pnpm arch:unusedKnip (human-readable)
pnpm arch:unused:jsongenerated/knip.json (always exit 0 via --no-exit-code; still review findings)
pnpm arch:flow:*generated/mmd/flows/<scenario>.{mmd,md} (+ optional .svg) — seed sequence diagrams
pnpm arch:perf:reportgenerated/performance/*.md templates — no auto profiling
pnpm arch:generated:indexWrites generated/index.html — lists outputs (TypeDoc is one link to api/index.html, not every file under api/)
pnpm arch:generated:serveRefreshes that index, then serves the folder on http://localhost:4000 (serve -l 4000)
pnpm arch:checkdependency-cruiser rules (no file outputs)
pnpm arch:updatedeps.dot + file graph + circular report
pnpm arch:allCore static pipeline (see root package.json)

Data sources (what is “real” vs “seed”)

SourceUsed by
Files under apps/, packages/, tools/code-symbols, hook complexity, props-flow, state heuristics
pnpm-workspace.yaml, package package.json filesC4 script
packages/app-contract/src/index.tsTypeDoc
dependency-cruiserarch:file-graph, arch:check
scripts/arch/c4-external.seed.jsonexternal systems on C4 diagram (not inferable from imports alone)
Default stringsruntime-flow scenarios (upgrade: Playwright trace + optional window.__PROX_OS_ARCH_TRACE__ — not injected into app code in v1)

C4 v1: roughly workspace auto-discovery plus a small seed for externals (Cloudflare, Neon, etc.). The split is intentional: external systems cannot be proven from repo imports alone.

AI-readable artifacts

  • Markdown / JSON under docs/architecture/generated/ are suitable for tools and agents. They are not copied into apps/docs by pnpm docs:sync (the generated/ tree is excluded on purpose). Human-authored Markdown and MDX elsewhere under root docs/ is mirrored into the docs app.
  • Mermaid .mmd can be pasted into viewers or rendered with @mermaid-js/mermaid-cli (mmdc). If mmdc fails (e.g. Chromium / pnpm approve-builds), .mmd remains the source of truth.
  • TypeDoc api.json reflects the app contract public types.

Do not treat PNG screenshots or draw.io exports as canonical architecture assets for this pipeline.

Knip: classification before any delete

Knip reports are candidates, not orders. Do not bulk-delete based on JSON output.

CategoryAction
Safe deleteOnly after proof: unused local helper, truly unused dependency, clearly abandoned temp file
Public API keepapp-contract exports, manifest types, package exports fields
Dynamic entry keepApp registry, localAppComponents, iframe/dev apps, Storybook stories, docs entry, config-only imports
Needs manual reviewAnything unclear — especially “unused export” in boundary packages

Local dependencies

  • Graphviz dot: required for SVG from arch:file-graph. Without it, you still get file-graph.dot.
  • mmdc: optional for SVG from Mermaid. @mermaid-js/mermaid-cli uses Puppeteer and needs a Chrome build. If mmdc errors with Could not find Chrome, run e.g. pnpm exec puppeteer browsers install chrome-headless-shell (or follow Puppeteer’s docs for your environment). You may also need pnpm approve-builds after adding the CLI. .mmd files remain valid without SVG.

Future work

  • Wire Playwright traces and optional archTrace instrumentation to replace or enrich seed arch:flow:* diagrams.
  • Surface generated/* in the in-shell Architecture app as read-only artifacts.

Build and Rendering Pipeline

Explain why the **OS Shell** uses Rsbuild/Rspack, how that differs from other apps in the monorepo, and how React 18 development behavior should influence shell

Package Graph

Próx OS is a pnpm workspace with apps and packages:

On this page

Why this existsWhat arch:all does and does not doCommand referenceData sources (what is “real” vs “seed”)AI-readable artifactsKnip: classification before any deleteLocal dependenciesFuture work