App Namespace, Domain, and Routing Strategy (Roadmap)

Status

This document is a roadmap and architecture seed for AI agents and maintainers. It is not a final API or routing contract. It does not authorize route rewrites, backend schema work, marketplace implementation, or billing logic.

For the current owner-scoped surface doctrine, read url-and-surface-model.md. Older candidate URL examples in this file are historical exploration unless they match that doctrine.

When implementing registry, API worker, App Store backend, auth, payments, database migrations, or runtime route changes, recommend Opt-in Slicing Mode and ask for explicit confirmation before entering it.

Owner-scoped surface doctrine

Future Prox OS should separate runtime routes, creator canonical URLs, and Store listing URLs.

Runtime routes open inside the OS shell and should stay clear:

/app-os/hola
/app-os/pricing
/app-hub/founder-suite
/app-hub/product-studio

Creator canonical URLs express ownership with one canonical @owner namespace. Owner can be a person or organization; that distinction belongs to permission, billing, and membership models, not to the root URL grammar.

/@esmadrider/apps/waitlist-pro
/@esmadrider/studios/indie-launch-kit
/@esmadrider/datasets/solo-founder-stack
/@esmadrider/studios/personal-lab

/@prox-os/apps/hola
/@prox-os/studios/founder-suite
/@prox-os/datasets/official-founder-stack
/@prox-os/studios/core-team

App Store listing URLs are discovery pages and must keep owner scope in the listing context:

/apps/@esmadrider/waitlist-pro
/apps/@prox-os/hola
/apps/@esmadrider/indie-launch-kit
/apps/@prox-os/founder-suite
/apps/@esmadrider/solo-founder-stack
/apps/@prox-os/official-founder-stack

Do not create default ownerless listing aliases such as /apps/waitlist-pro or /apps/founder-suite. Official, featured, verified, built-in, and community status belong in badges, tags, filters, collections, and curation metadata.

0. v0.2 URL strategy

Platform Foundation v0 should keep URLs conservative while the backend object model is still forming.

Phase 1: internal IDs first

Use stable internal IDs for the first backend-backed Studio and App routes:

/studio/:studioId
/apps/:appId

Notes:

• The shell has historical in-memory workspace route behavior. A server-backed Studio route must be designed carefully before it replaces or expands current local session behavior.
• Internal IDs avoid premature owner/slug migration work.
• Public sharing can remain limited until ownership, visibility, redirects, and slug claims are designed.

Phase 2: canonical owner/resource URLs

Later v0.2.x or v0.3 slices can add canonical owner-scoped public URLs:

/@username/runtime/:runtimeSlug
/@username/studios/:studioSlug
/@owner/apps/:slug
/@owner/datasets/:slug
/@owner/contexts/:slug

This keeps resource type explicit while preserving a GitHub-like owner mental model. It also avoids a bare /:owner/:repo route that would collide with shell, website, docs, API, and future system paths.

Profile routes: @owner

Use @owner routes for profile-centered browsing:

/@owner
/@username/runtime/:runtimeSlug
/@username/studios/:studioSlug
/@owner/apps

This gives user and organization profiles a shared owner/resource mental model without maintaining separate user and organization URL prefixes.

1. Subdomains are deployment origins, not app identity

Official hostnames (for example docs.prox-os.com, ui.prox-os.com, api.prox-os.com) are deployment origins and public entrypoints. They must not become the long-term primary app identity model.

Inside Próx OS, an app should be recognized by:

• Stable appId (primary key; does not change when slug, path, or marketing domain changes)
• namespace / creator / owner (owner, system, studio, …)
• slug (mutable display path segment; aliases and redirects handle renames)
• Manifest (launch mode, permissions, capabilities, visibility)
• Launch targets — routing.routeBase, iframeUrl, externalUrl, apiBaseUrl, etc. — as targets, not as identity

Do not assume: “add an app = register a new second-level subdomain under *.prox-os.com.”

Analogy (direction only, not a dependency): GitHub repos are github.com/:owner/:repo, not myrepo.github.com. Hugging Face uses huggingface.co/:owner/:model and huggingface.co/spaces/:owner/:space. Próx OS aims for a similar creator-owned namespace on paths, not per-app DNS by default.

2. Official infrastructure domains

These are platform infrastructure origins, not an open app namespace:

Do not turn root-level *.prox-os.com into an unlimited app registry (for example moments.prox-os.com, notes.prox-os.com, random-user-app.prox-os.com).

Why:

• Brand and naming collisions on a flat DNS namespace
• Weak expression of creator / org ownership
• Harder community graph, forks, remix, and permissions
• Cookie, CORS, CSP, iframe sandbox, and Access policy complexity
• High cost to rename, migrate, and revoke

A few official first-party products may still get dedicated marketing domains or official subdomains as a product decision — that is not the default onboarding path for apps.

3. Creator-owned path namespace (preferred exploration)

Candidate public URL shapes (not final; pick one family during registry RFC):

prox-os.com/@username/runtime/:runtimeSlug
prox-os.com/@username/studios/:studioSlug
prox-os.com/@owner/apps/:appSlug
prox-os.com/@owner/datasets/:datasetSlug
prox-os.com/@owner/contexts/:contextSlug
prox-os.com/@owner
prox-os.com/@owner/apps

Shorter variants such as /:creator/:appSlug should be treated cautiously because they can collide with system paths. Prefer explicit owner/resource URLs.

Current tendency:

• Prefer creator-owned paths for public canonical URLs and App Store discovery.
• Prefer owner/resource public URLs for Studios, Apps, Datasets, and Contexts once owner/slug routes exist.
• Do not default to moments.prox-os.com or moments.app.prox-os.com for first-party or community apps in early phases.
• Reserve official subdomains for infrastructure and rare branded products.

Benefits of path namespaces:

• URLs show who built what (prox/moments, esmadrider/moments).
• Different creators can use the same slug without DNS fights.
• Fits Studios, datasets, workflows, templates, and future community graph.
• Fork, remix, stars, installs align with path-stable appId + mutable slug.
• No per-app DNS operations for most launches.
• Renames via slug + alias + redirect without re-provisioning TLS.

4. Why not prioritize *.app.prox-os.com today

Patterns such as moments.app.prox-os.com or wildcard *.apps.prox-os.com are not the current recommendation. They may return later for runtime isolation, not as the default public identity.

Separation principle (future):

Public canonical route (shareable, SEO, App Store):
  prox-os.com/@esmadrider/apps/moments

Optional internal runtime origin (sandbox, stronger isolation) — later:
  app-01hxyz.apps.prox-os.com

Public identity route can be creator-owned path. Runtime isolation origin can be a generated subdomain later.

Do not conflate launch mode (iframe vs route vs external), app identity (appId), and runtime origin (where code executes).

5. Moments (first data app case study)

Moments is a candidate first data-heavy app (photos, feeds, search) — not in scope for this documentation pass to implement.

Identity: stable appId (for example moments or prox.moments — to be decided in RFC), plus namespace + slug.

Candidate public routes (roadmap candidates only):

prox-os.com/@esmadrider/apps/moments
prox-os.com/@prox-os/apps/moments
prox-os.com/apps/@esmadrider/moments
prox-os.com/apps/@prox-os/moments

API (candidate):

api.prox-os.com/v1/moments/*

Not recommended as default early choices:

• moments.prox-os.com
• moments.app.prox-os.com

If Moments later becomes a standalone marketed product, a custom domain or official subdomain can be added as a launch target alias without changing appId.

OS behavior: install, open window, permissions, and shortcuts flow through registry + app contract, not DNS naming.

6. System apps: Docs, UI Workshop, API Explorer

System apps have deployment origins but remain manifest-driven in the OS.

System apps may have deployment origins, but OS identity remains manifest-driven.

7. API origin and documentation visibility

api.prox-os.com is the official API origin, not a generic app tenant.

Candidate surfaces:

api.prox-os.com/v1/*              Runtime API
api.prox-os.com/openapi.json      OpenAPI schema
api.prox-os.com/docs              Scalar / API Explorer
api.prox-os.com/scalar            Explorer path candidate

Protection (roadmap):

• Runtime API: session / token, app permissions, rate limits, CORS, Cloudflare middleware (future).
• Docs / Scalar / OpenAPI: early Cloudflare Access (or equivalent); distinguish public vs internal OpenAPI later.

Seed types (documentation only — not implemented in packages/contracts/app-contract yet):

type ApiDocVisibility = 'public' | 'access-protected' | 'internal-only'

type ApiSurface = {
  id: string
  baseUrl: string
  openApiUrl?: string
  docsUrl?: string
  visibility: ApiDocVisibility
  audience: 'runtime' | 'developer' | 'internal-ai' | 'public'
}

8. App registry seed model (not final types)

Future backend and manifest evolution should treat domain and path as launch metadata, not primary keys.

type AppId = string

type NamespaceKind = 'owner' | 'system' | 'studio'

type AppNamespace = {
  kind: NamespaceKind
  handle: string // e.g. prox, esmadrider, community-ai
}

type AppLaunchMode = 'local-module' | 'route' | 'iframe' | 'external' | 'api-doc' | 'remote-module'

type AppRouteCandidate = {
  canonicalPath: string // e.g. /@esmadrider/apps/moments
  aliases?: string[]
  redirectsFrom?: string[]
}

type ProxAppManifestSeed = {
  appId: AppId // stable; never use domain as primary key
  namespace: AppNamespace
  slug: string
  displayName: string
  description?: string
  version?: string
  launchMode: AppLaunchMode
  route?: AppRouteCandidate
  iframeUrl?: string
  externalUrl?: string
  apiBaseUrl?: string
  permissions?: string[]
  capabilities?: string[]
  visibility: 'private' | 'unlisted' | 'public' | 'system'
  aliases?: string[]
  createdAt?: string
  updatedAt?: string
}

Governance rules:

• appId: immutable stable key for windows, permissions, analytics, and storage references.
• slug: may change; maintain aliases and HTTP redirects from old paths.
• namespace: encodes ownership; drives URL generation and App Store scope.
• Domains / iframe URLs: launch targets only; multiple targets can map to one appId.

Today's shell registry (ShellAppManifest, route groups) remains authoritative until a server-backed registry ships. See docs/platform/architecture/apps/app-registry.md and docs/platform/architecture/apps/app-contract-view.md.

9. Relationship to current shell routing

Today: OS shell uses route groups (/app/:appId, /app-admin/:appId, …) and window instances keyed by shell appId. That is an in-OS routing layer, separate from future public canonical URLs for sharing and App Store pages.

Convergence (future): public path prox-os.com/@x/apps/y may resolve to the same appId as /app/... inside the shell, via redirect or dual registration — to be designed in RFC, not assumed here.

10. Questions to narrow in a future RFC

1. Canonical path grammar: /@owner/resource/:slug plus resource-specific Store listing contexts.
2. How shell route groups relate to public paths (single router vs gateway).
3. When to introduce *.apps.prox-os.com runtime origins vs iframe-only isolation.
4. Custom domain mapping for published Studios (CNAME -> path or appId).
5. OpenAPI visibility tiers and OS iframe policy for API Explorer.
6. Final production deploy shape for docs.prox-os.com: static Pages export vs full Next runtime on Cloudflare Workers.

Related documents

• docs/platform/architecture/apps/app-registry.md — current registry and route groups
• docs/platform/architecture/apps/app-contract-view.md — manifest types and platform hosts
• docs/platform/architecture/runtime/runtime-view.md — managed links and API runtime
• docs/platform/architecture/repo/monorepo-workspace-guide.md — deployable apps per hostname
• docs/product/roadmap/platform/platform-roadmap.md — capability sequencing
• docs/development/ai/protocols/cost-gate.md — risk hints for routing/registry refactors