Architecture

Overview

User
  |
  v
COS / AI -------------------- Future Windows Apsule Builder
  |                                      |
  | edits the same Apsule Project        |
  +------------------+-------------------+
                     |
                     v
              Apsule Project
          JSON UI + JS + assets
                     |
                     v
                 Conductor
          (orchestration layer)
                     |
                     v
                   Relay
        (auth / transport / sessions)
                     |
                     v
              iPhone Apsule Host
        +---------------------------+
        | Project Manager           |
        | JSON -> SwiftUI Renderer  |
        | JavaScript Runtime        |
        | Reactive State Store      |
        | Host API Bridge           |
        +-------------+-------------+
                      |
          +-----------+-----------+
          | iOS frameworks        |
          | URLSession, MapKit,    |
          | CoreLocation, BLE ...  |
          +-----------------------+

Responsibilities

COS / AI

• Creates and edits Apsule Project files.
• Uses the documented schema instead of generating arbitrary SwiftUI.
• May query the connected runtime's supported features before generating a project.
• Does not need Relay-specific URLs or transport knowledge.

COS is one supported development client, not part of the project format. Codex, other agents, the official Builder, third-party tooling and humans editing files directly must be able to target the same contract.

Conductor

Conductor remains the orchestration boundary exposed to COS. Apsule-related operations should eventually be normalized Conductor capabilities such as:

• apsule.device.list
• apsule.project.list
• apsule.project.push
• apsule.project.get
• apsule.project.delete
• apsule.project.run
• apsule.project.stop
• apsule.runtime.status
• apsule.runtime.reload
• apsule.runtime.schema

Names are provisional until implemented. These are Conductor Capabilities, not Host APIs.

Relay

Relay should remain transport-oriented:

• authenticate endpoints;
• track connected iPhone Hosts;
• move project files/deltas and commands;
• carry runtime logs/errors/state inspection back toward PC/COS;
• maintain WebSocket sessions.

Relay should not interpret Apsule UI, execute JavaScript, or contain app-specific logic.

iPhone Host

The Host:

• stores Apsule Projects;
• validates project/runtime compatibility;
• renders JSON UI as native SwiftUI;
• executes project JavaScript in a controlled runtime;
• synchronizes reactive state with SwiftUI;
• exposes approved native functionality through Host APIs;
• enforces project permissions;
• receives project patches and Hot Reloads affected views;
• reports logs and runtime errors;
• exits a running Apsule back to Project Manager on the configured shake gesture.

Host API design should favor stable high-level wrappers plus narrowly scoped raw/provider primitives when doing so is safe. The purpose is to let Project JavaScript adopt new service-side features without requiring a new Apsule build for every endpoint. Raw/provider primitives must preserve Apsule's permission, credential-isolation, destination/method restriction and runtime-discovery boundaries; they are not an escape hatch around the Host security model. Features that require new entitlements, Info.plist declarations, extensions or compiled native support still require a Host update.

Only one project runtime is required to be active at a time initially. Stopping it destroys transient runtime execution while preserving project-scoped persistent data and explicitly OS-managed work such as already scheduled local notifications.

The Host keeps the last successfully installed project revision locally. Running an installed project must not inherently depend on the development PC, Relay, COS or an Apsule-operated cloud service.

Development kit and ecosystem boundary

The Apsule development contract should be usable without the official Builder:

• Apsule SDK / Spec: schemas, project/runtime contracts and reusable tooling interfaces.
• Apsule CLI: create/validate/pack/sync/run style workflows as they are implemented.
• Starter templates: valid projects that work with ordinary editors and agents.
• Apsule Skill: optional AI-facing guidance for agents that support skills; never a correctness/security boundary.
• Apsule Builder: the official visual GUI that reads/writes the same standard project format.

No Builder-only project format or COS-only metadata is allowed. Trustworthy identity, revision and permission enforcement lives in Apsule-controlled tooling/Host boundaries.

Fundamental boundary

Conductor Capability: apsule.project.push
        |
        v
Relay transport
        |
        v
iPhone Host
        |
        +-- JSON -> native SwiftUI
        |
        +-- JavaScript -> host.bluetooth.scan()
                         ^ Host API

Never conflate the two API families.