Repository Map

Root

prox-os/
  apps/
  packages/
  docs/
  infra/
  tools/
  AGENTS.md
  package.json
  pnpm-workspace.yaml
  nx.json
  mise.toml

Apps

apps/os-shell

The main browser OS Shell application.

Responsibilities:

• Desktop surface
• Window manager
• Dock
• Top bar
• App launcher
• Shell-level state
• Routing
• Composition of local apps

Should import:

• @prox-os/os-ui
• @prox-os/app-contract
• @prox-os/os-actions when ready

Should not own:

• Database schema
• Cloudflare Worker routes
• Object storage secrets

apps/api-worker

The Hono + Cloudflare Workers API application.

Responsibilities:

• API routes
• Runtime environment bindings
• Auth boundary when introduced
• Calling database and storage packages
• Exposing platform actions over HTTP

Should import:

• @prox-os/db
• @prox-os/storage
• @prox-os/os-actions
• @prox-os/app-contract

Should not import:

• apps/os-shell

apps/mcp-server Future

Future MCP server for AI tools.

Responsibilities:

• Expose selected platform capabilities as MCP tools
• Reuse packages/os-actions
• Avoid duplicating business logic

Packages

packages/ui/os-ui

Reusable OS Shell UI primitives.

Examples:

• Surface
• GlassPanel
• IconButton
• Separator
• TopBar
• Dock
• Titlebar
• WindowFrame

Must not import database or API code.

packages/contracts/app-contract

Protocol and type definitions for apps, windows, permissions, and data scopes.

Examples:

• AppManifest
• WindowManifest
• Permission
• DataScope

Must stay implementation-neutral.

packages/data/db

Database schema and access utilities.

Responsibilities:

• Drizzle schema
• Migrations
• Database client
• Seed utilities
• Query helpers

packages/backend/storage

Object storage abstraction.

Responsibilities:

• R2 / S3-compatible config
• Upload helpers
• Presigned URL helpers
• Asset provider abstractions

packages/os-actions

Reusable platform actions.

Future examples:

• listApps
• queryDataset
• createBookmark
• getArchitectureMap

These should be reusable by API routes, future MCP tools, and selected UI flows.

Docs

docs/development/ai

AI collaboration and agent context.

docs/platform/architecture

System architecture views.

docs/platform/data

Data model and schema decisions.

docs/platform/db

Database roles, permissions, and operational guidance.

docs/product/design

Design language and UI system guidance.

docs/business/governance

Governance Console, knowledge-base strategy, contribution lifecycle, asset ownership, and founder succession readiness.

docs/business/roles

Human role specs and AI agent role indexes. Human roles and AI agent roles must remain separate.

docs/operations/performance

Performance budget and review guidance for the OS Shell and official apps.

docs/trust/security

Access, secrets, contributor permissions, and AI work product policies.

docs/trust/readiness

EU/GDPR, APAC/China, global entity, data, deployment, and payment readiness. Focused China notes live under docs/trust/readiness/apac/china; global region notes live under docs/trust/readiness/global/regions.

docs/business/payments

Founder Preview billing, Stripe test mode, activation codes, subscriptions, regional pricing, marketplace revenue splits, and payment risk register.

docs/business

Collaboration, customers, investors, VC readiness, IP/trademark, invoicing, regional pricing, and commercial war-room notes.

docs/business/contributors

APAC partner roadmap, contributor incentives, clean-room IP rules, downgrade, exit, and agreement template index.

docs/platform

Long-term Proxied Apps, multi-tenant Spaces, MCP agent worker swarm, mobile Web OS, desktop, and super-app evolution.

docs/business/bad-ideas

Anti-patterns and risky shortcuts documented as internal boundary-setting, not instructions.

docs/go-to-market/decks

Deck workflow and outline documents.

docs/development/tooling

Candidate software, AI, design, and ops tooling maps.

docs/operations

Deployment, incident notes, runbooks, and local operations.