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. When implementing registry, API worker, or App Store backends, run Triage / RFC per docs/ai/cost-gate.md and narrow choices with an ADR.

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 (user, org, system, space, …)
• slug (mutable display path segment; aliases and redirects handle renames)
• Manifest (launch mode, permissions, capabilities, visibility)
• Launch targets — routePath, 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/:creator/:appSlug
prox-os.com/:creator/apps/:appSlug
prox-os.com/@:creator/:appSlug
prox-os.com/apps/:creator/:appSlug
prox-os.com/user/:userHandle/app/:appSlug
prox-os.com/org/:orgHandle/app/:appSlug
prox-os.com/space/:spaceSlug/app/:appSlug
prox-os.com/spaces/:creator/:spaceSlug
prox-os.com/datasets/:creator/:datasetSlug

Early-route candidates (roadmap only):

prox-os.com/user/:userHandle/app/:appSlug
prox-os.com/org/:orgHandle/app/:appSlug
prox-os.com/space/:spaceSlug/app/:appSlug

Shorter variants may also be evaluated: /:creator/app/:appSlug, /:creator/:appSlug, /@:creator/:appSlug.

Current tendency:

• Prefer creator-owned paths for public canonical URLs and App Store discovery.
• 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 spaces, 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/user/esmadrider/app/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/user/esmadrider/app/moments
prox-os.com/org/prox/app/moments
prox-os.com/@esmadrider/moments
prox-os.com/prox/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/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 = 'user' | 'org' | 'system' | 'space'

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. /user/esmadrider/app/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/architecture/app-registry.md and docs/architecture/app-contract-view.md.

9. Relationship to current shell routing

Today: OS shell uses route groups (/app/:appId, /app-dev/: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/user/x/app/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: /@creator/slug vs /user/:handle/app/:slug vs both with aliases.
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 spaces (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/architecture/app-registry.md — current registry and route groups
• docs/architecture/app-contract-view.md — manifest types and platform hosts
• docs/architecture/runtime-view.md — managed links and API runtime
• docs/architecture/monorepo-workspace-guide.md — deployable apps per hostname
• docs/roadmap/platform-roadmap.md — capability sequencing
• docs/ai/cost-gate.md — required before XL routing/registry refactors