Spatial App Architecture

Spatial App Architecture

Quick Start

Use this skill for architecture questions, not API questions.

Use it when:

• you need to choose the right surface: window, volume, immersive space, or a

mixed flow

• you are deciding which state is app-wide, scene-scoped, immersive-scoped, or

view-local

• a root file owns too many concerns and needs a refactor plan
• you need a file or module plan before writing or splitting SwiftUI code

Load References When

Workflow

1. Classify the feature by user job and current or intended surface. 2. Choose the owning surface model: window, volume, immersive space, or a combination. 3. Assign state ownership boundaries: app, scene, immersive, feature, view. 4. Choose a file/module shape that matches the ownership model. 5. Define the implementation handoff: SwiftUI, RealityKit, ARKit, SharePlay, or build/debug. 6. If this is a refactor, sequence the extraction so behavior stays stable. 7. Verify the structure with build-run-debug after the first usable slice.

When To Switch Skills

• Switch to spatial-swiftui-developer when the surface and ownership model

are already chosen and the next step is implementing SwiftUI APIs.

• Switch to realitykit-visionos-developer when the work is mainly about

entities, components, systems, or RealityKit runtime behavior.

• Switch to arkit-visionos-developer when the architecture choice depends on

provider constraints, anchors, or tracked-world behavior.

• Switch to shareplay-developer when the app structure is driven by group

activity or shared immersive presence.

• Switch to build-run-debug after the first usable architectural slice exists

and needs validation.

Guardrails

• Do not choose immersion by novelty alone.
• Do not let transient views own long-lived immersive lifecycle or RealityKit

mutation.

• Preserve strong repo conventions when they are already coherent.

Output Expectations

Provide:

• the chosen surface model and why
• the ownership map: app, scene, feature model/coordinator, reality owner, view
• the proposed file/module shape
• the refactor slices, if this is brownfield work
• the next implementation handoff:

spatial-swiftui-developer, realitykit-visionos-developer, arkit-visionos-developer, shareplay-developer, or build-run-debug

Architecture Anti-Patterns

Use this file when you need to explain why the current structure is unstable.

• One giant ContentView owns every surface and lifecycle.
• Scene selection, state ownership, networking, and RealityKit mutation sit in

one file.

• Leaf controls quietly own immersive entry or dismissal.
• Top-level branching swaps between unrelated roots without a stable owner.
• The design forces iOS-style stacked navigation onto a spatial flow without a

strong reason.

• The team chose RealityView or ARKit before deciding the surface and

ownership model.

• A volume is treated like a disposable preview even though it owns workflow

state that must survive window updates.

• openImmersiveSpace is called from several leaf buttons with no shared

session state or failure handling.

• Attachments contain the inspector for the whole app instead of a compact

in-scene control or label.

• RealityView update closures start asset loads or add duplicate root

entities on every state change.

File Layouts

Use this file when the app needs a proposed file or module shape.

Layered Scene-First Shape

• App/<AppName>App.swift
• Scenes/<Feature>Scene.swift
• Views/<Feature>RootView.swift
• Views/<Feature>DetailView.swift
• Models/*.swift
• Stores/*.swift
• Services/*.swift
• Support/*.swift

Use this when the codebase is already layered or when multiple scenes share the same services and models.

Feature-Sliced Shape

• App/<AppName>App.swift
• Scenes/MainWindowScene.swift
• Scenes/ImmersiveRootScene.swift
• Features/<Feature>/<Feature>View.swift
• Features/<Feature>/<Feature>Model.swift
• Reality/<Feature>RealityController.swift

Use this when a spatial feature has strong ownership boundaries that deserve to stay together.

Mixed Surface Feature Shape

• Scenes/<Feature>WindowScene.swift
• Scenes/<Feature>VolumeScene.swift
• Scenes/<Feature>ImmersiveScene.swift
• Features/<Feature>/<Feature>Coordinator.swift
• Features/<Feature>/<Feature>State.swift
• Features/<Feature>/<Feature>ControlsView.swift
• Features/<Feature>/<Feature>ImmersiveView.swift
• Features/<Feature>/<Feature>RealityController.swift

Use this when one user workflow crosses a window, bounded volume, and immersive space. Keep scene declarations separate from views so launch behavior, restoration, IDs, and default sizes are easy to audit.

Naming Defaults

• Name scene files after the surface they declare.
• Name coordinators after the workflow they coordinate, not after SwiftUI.
• Name RealityKit owners RealityController, RealityScene, or System

according to the repo's existing convention.

• Keep attachments near the Reality owner when placement is core behavior; keep

ordinary panels near SwiftUI views when they are just controls.

If the repo already has a stronger convention, preserve it rather than forcing a new global layout.

Refactor Playbook

Use this file when the app already exists and the structure is the problem.

Sequence

1. Identify the current root owner and list the concerns it mixes. 2. Freeze the scene boundary first: app declaration, launch scene, secondary windows/volumes, and immersive spaces. 3. Add a thin compatibility adapter if existing call sites are noisy, then move state to the correct owner before splitting views further. 4. Extract immersive lifecycle into a scene/session coordinator with explicit intents (open, dismiss) and phases (closed, opening, open, failed) when the current code needs them. 5. Extract RealityKit mutation into a named controller or system. Keep RealityView closures as the bridge, not the whole feature brain. 6. Split files by responsibility, not by arbitrary line count. 7. Replace broad globals with explicit environment injection only after the new owner exists. 8. Re-run build and launch after each meaningful extraction slice.

Refactor Slices

• Scene slice: move WindowGroup, Window, ImmersiveSpace, launch

behavior, and scene IDs into obvious app/scene files.

• State slice: move selection, loading, preferences, and immersive status to

the ownership level that actually needs to persist them.

• Reality slice: move entity lookup, component writes, subscriptions,

attachments placement, and animation control into a Reality owner.

• View slice: leave views with layout, local controls, bindings, and intent

dispatch.

• Verification slice: build, launch, open/dismiss every surface, and confirm

the old entry path still works.

Review Checks

• Can a reader name the owner of each scene and each long-lived model?
• Can the immersive space be opened, fail, and dismiss without stranded state?
• Are attachments created by SwiftUI but positioned by the Reality owner?
• Did the refactor avoid mixing visual cleanup with ownership changes?
• Does each extracted file have a reason beyond reducing line count?

Goal

Keep behavior stable while making ownership and scene boundaries explicit.

State Ownership

Use this file when deciding what owns state and lifecycle responsibilities.

Ownership Map

State Placement Defaults

• @State: local control state and small scene-owned observable models
• @Binding: parent-owned state passed into a child
• @SceneStorage: scene-local restoration when it genuinely fits
• @AppStorage: app-wide preference or toggle
• @Environment(Type.self): shared service, coordinator, or app context when

that matches the project convention

• @Observable: default model/coordinator shape for new SwiftUI and visionOS

state unless an existing repo convention or explicit compatibility blocker requires a different pattern

Boundary Rules

• Put openImmersiveSpace, dismissImmersiveSpace, openWindow, and

dismissWindow calls behind scene-level intent methods when several controls can trigger them.

• Keep entity references and subscriptions in a named RealityKit owner, not in

throwaway SwiftUI rows or buttons.

• Let views describe user intent. Let coordinators decide whether that intent

changes navigation, opens a scene, loads assets, or mutates entities.

• Treat attachments as part of the RealityKit presentation boundary: SwiftUI

owns their view content; the Reality owner owns their 3D placement.

• Make cross-surface state explicit. If a selection appears in a window and an

immersive space, put it in a shared scene/app model instead of duplicating it.

Do not keep immersive lifecycle ownership or long-lived entity ownership in transient leaf views.

Surface Selection

Use this file when the main question is which surface should own the feature.

Surface Defaults

Treat a volume as a window scene with windowStyle(.volumetric), not as a lightweight immersive space. Treat ImmersiveSpace as a separate scene with separate lifecycle, environment actions, and one-open-space-at-a-time behavior.

Decision Sequence

1. Name the user job first: browse, edit, inspect, present, simulate, watch, collaborate, or debug. 2. Pick the least immersive surface that satisfies that job. 3. Decide the launch surface. Most apps should start in a normal window unless the product is inherently immersive. 4. Decide whether 3D content is bounded. Bounded content usually belongs in a volume or RealityView inside a window; unbounded content belongs in an immersive space. 5. Decide which scene owns open/dismiss actions before writing UI controls. 6. Write down what state must cross surface boundaries.

Lifecycle Questions

• Does the surface open automatically or on demand?
• Who owns openImmersiveSpace and dismissImmersiveSpace?
• Which state must survive the transition between surfaces?
• Should the scene restore on relaunch, use defaultLaunchBehavior, or be

suppressed until explicitly opened?

• Does the app need a unique Window, multiple WindowGroup instances, a

volume, or exactly one immersive session?

• What happens when the immersive space fails to open, is dismissed externally,

or is interrupted by another immersive experience?

API Contract Pointer

This file owns surface choice. For exact SwiftUI scene APIs, open/dismiss actions, and restoration behavior, load `swiftui-scene-lifecycle.md`.

Common Surface Combinations

• Window + volume: window owns navigation, selection, and commands; volume

owns bounded 3D preview or manipulation.

• Window + immersive space: window owns entry, exit, settings, and recovery;

immersive scene owns presence, simulation, media, or ARKit/RealityKit runtime.

• Volume + immersive space: use only when a bounded 3D staging area has a

clear handoff into a full environment. Do not make the user manage two 3D surfaces without a strong workflow reason.

• Multiple windows: use stable IDs and explicit ownership when independent

tools or documents can coexist; avoid scattering one feature's lifecycle controls across several scenes.

Output Shape

When answering, include:

• selected launch surface and secondary surfaces
• why the selected surface is the least immersive one that satisfies the job
• scene IDs and open/dismiss ownership if the feature spans scenes
• state that must cross surface boundaries
• the fallback path when opening a secondary surface fails