URL And Surface Model

Status

This document is architecture doctrine and roadmap guidance. It does not change current runtime routes, router behavior, database schema, App Store backend, or marketplace implementation.

Current runtime routes such as /app-os/hola, /app-os/pricing, and /app-hub/founder-suite stay registry-driven. Future owner-scoped canonical paths and Store listing paths should be connected through metadata, not by migrating the shell runtime route shape into creator or Store paths.

Surface

A Surface is the generic OS-visible resource that Prox OS can open, install, reference, pin, collect, display, or list. It is more general than an app.

Documentation-only sketch:

type SurfaceType =
  | 'app'
  | 'hub'
  | 'collection'
  | 'folder'
  | 'space'
  | 'module'
  | 'external'
  | 'system'

Rules:

Rule	Meaning
Marketplace is optional	Not every surface enters the marketplace.
Runtime is optional	Not every surface is runnable.
URL addressability is optional	Not every v1 surface needs to be URL-addressable.
URL is not identity	A URL is a route or path binding, not the resource identity itself.
Stable ids matter	`surfaceId` should be more stable than route strings, slugs, or display titles.

Resource Boundaries

Resource	Boundary
`App`	A single runnable product surface. It should not contain other apps.
`Hub`	A runnable product bundle or workspace that can include apps and internal modules.
`Collection`	A curated list or editorial playlist. It references apps, hubs, spaces, templates, or links; it owns none.
`Folder`	User-defined desktop organization for shortcuts and layout. It is not a marketplace product by default.
`Space`	A personal, project, or collaboration context with members, permissions, installed surfaces, and data.
`Module`	A Hub-internal incubation unit that can later be promoted into an App.
`External`	A URL, SaaS dashboard, repo, file, or outside resource represented inside the OS.
`System`	Shell-owned or infrastructure surface that is not a marketplace listing by default.

Relationship verbs should stay precise:

Actor	Verb	Target
Owner	owns	Surface
Space	installs	Surface
Collection	references	Surface
Folder	shortcuts	Surface
Hub	includes	App or Module

Do not flatten all relationships into recursive nested ownership.

Runtime Route, Creator Canonical URL, Store Listing URL

Prox OS should keep three URL concepts separate.

URL concept	Example routes	Meaning	Rule
Runtime route	`/app-os/hola`, `/app-os/pricing`, `/app-hub/founder-suite`, `/app-hub/product-studio`	Opens inside the OS shell.	Runtime route groups remain registry-driven; do not migrate `/app-os/*` to owner canonical paths.
Owner canonical URL	`/@esmadrider`, `/@esmadrider/apps/waitlist-pro`, `/@esmadrider/runtime/os`, `/@esmadrider/studios/personal-lab`, `/@esmadrider/datasets/solo-founder-stack`, `/@esmadrider/library/apps/hola`, `/@prox-os`, `/@prox-os/apps/hola`, `/@prox-os/studios/core-team`, `/@prox-os/datasets/sample`	Expresses ownership, authorship, governance, versioning, and future revenue split identity.	The canonical owner prefix is `@owner`; user and organization distinctions belong to permission, billing, membership, and governance models.
Store listing URL	`/apps/@esmadrider/waitlist-pro`, `/apps/@prox-os/hola`	Discovery page for a published app owner.	Concrete listings include the owner.
Type-level discovery	`/apps`, `/datasets`, `/community`	Public discovery pages for categories.	These can remain ownerless because they are not listing aliases.
Disallowed ownerless alias	`/apps/waitlist-pro`	Short app listing without owner identity.	Do not create this default pattern.

Ownerless aliases create unfair name claims, review disputes, and weak creator identity. Official, featured, verified, built-in, and community status should be badges, tags, filters, collections, or curation metadata, not namespace ownership.

Metadata Bridge

Future metadata should bind runtime route, creator path, and Store path without changing current shell routes.

const holaSurface = {
  id: 'hola',
  surfaceType: 'app',
  ownerType: 'organization',
  ownerHandle: '@prox-os',
  runtimeRoute: '/app-os/hola',
  creatorPath: '/@prox-os/apps/hola',
  storePath: '/apps/@prox-os/hola',
  badges: ['official', 'built-in'],
}

const founderSuiteSurface = {
  id: 'founder-suite',
  surfaceType: 'hub',
  ownerType: 'organization',
  ownerHandle: '@prox-os',
  runtimeRoute: '/app-hub/founder-suite',
  creatorPath: '/@prox-os/studios/founder-suite',
  storePath: '/apps/@prox-os/founder-suite',
  badges: ['official', 'built-in', 'incubating'],
}

These are examples only. Do not implement the routes or backend registry from this document alone.

Revenue Split And Ownership

Revenue split requires explicit owner namespace:

Split input	Why it matters
Hub owner	Owns the bundle or workspace surface.
Included app owners	Prevents bundled apps from losing attribution.
Contributor identities	Supports future contributor compensation.
Platform fee	Keeps platform economics explicit.
Usage-based or weight-based split	Allows fair allocation when multiple surfaces drive value.
Manual split policy	Handles negotiated or curated products.
Subscription pool	Supports bundle or membership revenue models.

Official, featured, and verified badges are not ownership. Revenue split should bind to canonical owner identity and included surface metadata, not to short URL aliases.

Document	Use
Hub App Model	Hub and module product shape.
App Store Surfaces	Store discovery and listing posture.
Space, Desktop, And Window Session	Session, scene, and window boundaries.
App Namespace And Domain Strategy	Creator namespaces and future domain direction.
App Registry	Current runtime registry facts.
App Contract View	App contract and surface metadata direction.