Repository Map

Root

prox-os/
  apps/
  packages/
  docs/
  infra/
  tools/
  AGENTS.md
  package.json
  pnpm-workspace.yaml
  turbo.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/os-ui

Reusable OS Shell UI primitives.

Examples:

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

Must not import database or API code.

packages/app-contract

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

Examples:

• AppManifest
• WindowManifest
• Permission
• DataScope

Must stay implementation-neutral.

packages/db

Database schema and access utilities.

Responsibilities:

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

packages/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/ai

AI collaboration and agent context.

docs/architecture

System architecture views.

docs/data

Data model and schema decisions.

docs/db

Database roles, permissions, and operational guidance.

docs/design

Design language and UI system guidance.

docs/operations

Deployment, incident notes, runbooks, and local operations.