The 14 layers of Surface OS

PWFabric organizes digital experience creation into 14 distinct operating system layers. Each layer is a clear boundary with its own contracts, implementations, and APIs.

Per ADR-153 the 14 layers are the architectural taxonomy — not a one-to-one route map. Most layers are exposed inside the Phico Studio canvas through modal panels and sidebars (a pattern shared with Figma, Linear, and Notion) rather than dedicated top-level pages.

Architecture overview

Traditional frameworks treat UI as a single concern. PWFabric decomposes it into an operating system with distinct layers — just like a computer OS has process management, memory, file systems, and I/O.

#	Layer	Purpose	Where it lives today
1	Identity & Context	Who is interacting, session management	Account app: `/login`, OAuth callbacks
2	Surface Graph	Topology of all surfaces	Not yet implemented (parked)
3	Surface Lifecycle	Birth, evolution, publication	Phico: `/library/surfaces`, revision history modal
4	Spatial Composition	Geometry and structure (blocks)	Phico Canvas (the main editor)
5	Semantic Reality	What surfaces mean (entities)	Phico `AddBlockModal → Entities`; Operator `/platform/entities` (staff)
6	Capability Fabric	Powers surfaces can have	Phico `AddBlockModal`, `SurfaceSettingsModal`, `CapabilitySection`
7	Behavior & Orchestration	Logic and automation	Phico `AddBlockModal → InteractionOperationalSection`; Operator `/platform/behavior-rules` (staff)
8	Surface Memory	State and persistence	Phico `RightPanel`, `DataTools`, `CapabilityDataSources`
9	Connectivity Fabric	External integrations	Phico `AddBlockModal → DataPage`; Account `/developer` (OAuth M2M); Operator `/platform/connectors` (staff)
10	Surface Intelligence	AI and evolution	Phico `RightPanel → AssistantPanel`; Account `/settings/ai`
11	Execution & Runtime	Live execution	Server-side runtime — no dedicated UI
12	Observability	Metrics and monitoring	Account `/analytics` (world-scoped); Operator `/platform/analytics` (staff, cross-world)
13	Ecosystem Economy	Marketplace and licensing	Phico `/marketplace`; Account `/billing`, `/wallet`
14	User Context	Personal context and settings	Account `/settings/*` (identity, AI, members, teams, audit, SSO, danger)

Most layers live inside the Phico Studio canvas via modal panels and sidebars — primarily the AddBlockModal (a workspace hub with operational sections per capability) and the RightPanel (AI composer and property inspector). One layer is intentionally parked: Layer 2 (Surface Graph topology view) — pending product demand.

Layer deep dives

1. Identity & Context

Entry point to the surface universe. Manages authentication, sessions, and organizational context.

Contracts: UserId, SessionId, OrganizationId, AuthToken
Capabilities: Single sign-on, multi-tenancy, role-based access

2. Surface Graph

The topology layer. Tracks relationships between all surfaces — parent/child, references, dependencies.

Contracts: SurfaceGraph, SurfaceNode, SurfaceEdge, GraphQuery
Capabilities: Surface discovery, dependency tracking, graph visualization

3. Surface Lifecycle

Manages the complete lifecycle of surfaces from creation to retirement.

Contracts: SurfaceLifecycle, Version, Publication, Archive
Capabilities: Version control, branching, publication workflow, rollback

4. Spatial Composition

The geometry engine. Handles block composition, layout, and responsive behavior.

Contracts: Block, BlockTree, Layout, Responsive
Capabilities: Visual builder, responsive preview, layout templates

5. Semantic Reality

What surfaces mean, not just how they look. Entity definitions, schemas, and semantic bindings.

Contracts: Entity, EntitySchema, SemanticBinding, Ontology
Capabilities: Data modeling, schema validation, entity relationships

6. Capability Fabric

The power network. Manages which capabilities are available and how they’re configured.

Contracts: Capability, CapabilityConfig, CapabilityBinding, Permission
Capabilities: Capability marketplace, configuration UI, dependency resolution

7. Behavior & Orchestration

The nervous system. Rules, triggers, workflows, and automation logic.

Contracts: Behavior, Rule, Trigger, Workflow, Action
Capabilities: Visual workflow builder, event triggers, conditional logic

8. Surface Memory

Consciousness layer. State management, persistence, and context awareness.

Contracts: State, Store, Persistence, Context
Capabilities: State debugging, persistence config, context visualization

9. Connectivity Fabric

External integrations. Connectors, adapters, and protocol bridges.

Contracts: Connector, Adapter, Protocol, Integration
Capabilities: Connector marketplace, OAuth flows, webhook management

10. Surface Intelligence

AI and evolution. Machine learning, optimization, and adaptive behavior.

Contracts: AICapability, Embedding, Prediction, Optimization
Capabilities: Content generation, performance optimization, behavior prediction

11. Execution & Runtime

Live execution layer. Rendering, hydration, and runtime coordination.

Contracts: Runtime, Renderer, Hydration, Execution
Capabilities: Edge deployment, SSR/SSG, performance monitoring

12. Observability

Behavior reading. Metrics, logs, traces, and analytics.

Contracts: Metric, Log, Trace, Analytics
Capabilities: Real-time dashboards, alerting, performance insights

13. Ecosystem Economy

Marketplace and licensing. Discovery, distribution, and monetization.

Contracts: Listing, License, Transaction, Review
Capabilities: Marketplace publishing, license management, revenue tracking

14. User Context

Personal context. Preferences, history, and cross-surface user state.

Contracts: UserPreference, UserHistory, PersonalContext
Capabilities: Settings management, usage history, cross-surface context

Layer dependencies

Layers have clear dependency rules. Lower layers don’t know about higher layers:

Layer 1 (Identity)              ← Foundation layer
  ↓
Layer 2-3 (Graph, Lifecycle)    ← Structure layers
  ↓
Layer 4-5 (Spatial, Semantic)   ← Definition layers
  ↓
Layer 6-10 (Capabilities...)    ← Enhancement layers
  ↓
Layer 11-12 (Runtime, Obs)      ← Execution layers
  ↓
Layer 13-14 (Economy, User)     ← Experience layers

Working with layers

Build surfaces — Layers 4, 6. Spatial Composition + Capability Fabric to create experiences.
Add intelligence — Layer 10. Integrate AI capabilities for content and optimization.
Connect systems — Layer 9. Use Connectivity Fabric for external integrations.
Monitor performance — Layers 11, 12. Runtime + Observability for production insights.

API reference

Each layer exposes its own API endpoints. See the API documentation for complete reference, or explore the World physics for architectural context.

Overview World physics