Architecture

Technical spine. Reads after PRODUCT_SPEC.md. Codifies the sandboxing model, data schemas, Claude API integration, multi-tenancy plan, and the choices that lock in for the next year.

Status: locked 2026-04-27 for Phase A. Phase D revisits. Bar: every decision is justified. Nothing left as “we’ll figure it out.”

1. The stack today (Phase 1–2.5)

What’s already shipped, for the record:

┌─────────────────────────────────────────────────────┐
│  Browser PWA                                         │
│  https://kiwimaddog2020.github.io/ensemble-dashboard │
│                                                      │
│  • SHARED_HEAD (link to style.css + FOUC + SW)       │
│  • All CSS in style.css (single source of truth)     │
│  • SHARED_NAV / FOOTER / SCRIPTS (one shell)         │
│  • Widget engine (19 widgets, sectioned layout)      │
│  • Service worker (ensemble-v3-phase2 cache)         │
│  • Bearer token auth from localStorage               │
└─────────────┬───────────────────────────────────────┘
              │ HTTP (same origin in PWA, Cloudflare Tunnel to phone)
              ▼
┌─────────────────────────────────────────────────────┐
│  Mac-local control panel (Python BaseHTTPHandler)    │
│  bin/control-panel-server.py on :8080                │
│                                                      │
│  • /health, /state (GET, auth required)              │
│  • /fire, /kill, /set-config, /set-state (POST)      │
│  • /freeze-until, /pause-autopilots, /release-lock   │
│  • /chat-message, /chat-reread, /toggle-active …    │
│  • Bearer token from ~/.claude/orchestrator/.env.local│
└─────────────┬───────────────────────────────────────┘
              │ direct file I/O
              ▼
┌─────────────────────────────────────────────────────┐
│  File-based state                                    │
│  ~/.claude/orchestrator/                             │
│                                                      │
│  • state.json (system state, atomic write)           │
│  • chats/*.json (one per chat/agent)                 │
│  • state.lock.d/ (workshop lock — atomic mkdir)      │
│  • runs/ (autopilot session logs)                    │
│  • queue/ (autopilot fire triggers)                  │
└─────────────────────────────────────────────────────┘

Single-user, single-machine. Distributed across Mac + iOS (PWA + Cloudflare Tunnel). No cloud backend, no database server. State is plain JSON on disk; concurrency is mkdir-as-lock; atomicity is tmp + os.replace.

This stack is the substrate Phase A builds on. We do not change it for Phase A.

2. Phase A architecture (Studio v1)

What gets added in Phase A. Single-user, no cloud. Lives entirely on top of the existing stack.

2.1 New files in the dashboard build

bin/dashgen/
├── pages/
│   ├── studio_body.py         (NEW — the Studio shell + tab UX)
│   └── (existing files)
├── studio/
│   ├── presets/
│   │   ├── orchestra.json     (NEW)
│   │   ├── jazz_combo.json    (NEW)
│   │   ├── spaceship_crew.json(NEW)
│   │   ├── fellowship.json    (NEW)
│   │   └── dev_team.json      (NEW)
│   ├── sprites/
│   │   ├── core/              (NEW — 80 SVG/PNG files)
│   │   └── extended/          (NEW — 200 SVG/PNG files)
│   ├── sounds/
│   │   ├── ambient/           (NEW — 5 looping mp3s, one per preset)
│   │   └── action/            (NEW — ~20 short mp3s)
│   └── studio_engine.py       (NEW — Python that bundles JS engine)
├── widgets/
│   ├── engine_js.py           (existing — adds studio-preview widget)
│   └── studio_engine_js.py    (NEW — the Studio rendering + edit engine, ~3000 lines)
└── styles/
    └── studio.py              (NEW — Studio-specific CSS, ~1500 lines)

The Studio engine is a separate JS bundle (studio_engine_js.py → emits as /studio.js at build time) loaded only on the Studio page. The dashboard’s existing engine (engine_js.py) doesn’t grow.

2.2 New files in user data

~/.claude/orchestrator/
├── studio/
│   ├── room.json              (NEW — the user's current Room state)
│   ├── room.draft.json        (NEW — auto-save draft, recoverable)
│   ├── history/               (NEW — versioned snapshots of room.json)
│   └── user_sprites/          (NEW — Claude-generated + uploaded sprites)
└── (existing)

room.json is the single source of truth for the user’s Room. studio_engine_js reads + writes it via the control panel’s new /studio endpoints (see §2.3).

2.3 New control-panel endpoints (bin/control-panel-server.py)

GET    /studio/room                  → returns current room.json
PUT    /studio/room                  → writes room.json (auth required, atomic)
GET    /studio/presets               → lists built-in presets + user-saved
POST   /studio/presets/save          → saves current room as named preset
POST   /studio/presets/load/:name    → loads a preset into room.json
GET    /studio/sprites               → lists all sprites (built-in + user)
POST   /studio/sprites/upload        → uploads SVG/PNG, returns sprite ID
POST   /studio/claude/sprite         → proxies to Claude API for sprite generation
POST   /studio/claude/component      → proxies to Claude API for component generation
POST   /studio/claude/chat           → proxies to Claude API for free-form chat
GET    /studio/history               → lists snapshots
POST   /studio/history/restore/:id   → restores a snapshot to room.json

All POST endpoints auth-gate on Bearer token (existing pattern). The /studio/claude/* endpoints proxy to Anthropic’s API using the user’s ANTHROPIC_API_KEY from .env.local — see §6.

2.4 Render flow

Browser opens /studio.html
  ↓
SHARED_HEAD applies (theme, FOUC, body class "hub studio")
  ↓
Studio engine boots (studio_engine_js.py)
  ↓
Engine fetches /studio/room → renders View mode by default
  ↓
Each Component is rendered into a <div class="studio-component" data-id="…">
  ↓
Live components subscribe to refreshState() (existing 60s loop)
  ↓
Animations run via CSS transitions + requestAnimationFrame for canvas/SVG
  ↓
[Owner clicks Edit]
  ↓
Engine enters edit mode → palette + Claude chat drawers slide in
  ↓
[User drags, codes, prompts Claude, etc.]
  ↓
Auto-save fires every 5s → PUT /studio/room

3. Sandboxing model — the critical piece

The Studio lets users write arbitrary HTML/CSS/JS. That code must: - Render correctly inside a Room. - Read data from chat state (when bound). - React to events from other components. - Not be able to break the parent page. - Not be able to read localStorage / cookies / any sensitive data. - Not be able to make network requests outside an allowlist.

Approach: every Custom (code) component runs inside a sandboxed iframe with a strict Content Security Policy.

3.1 Iframe configuration

<iframe
  class="studio-custom-component"
  data-component-id="abc123"
  sandbox="allow-scripts"
  csp="default-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; media-src 'self' blob:; font-src 'self'; connect-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none';"
  srcdoc="...user code wrapped in shell..."
></iframe>

The sandbox="allow-scripts" attribute (note: NO allow-same-origin) means: - Scripts run, but the iframe is treated as a “null origin.” - It cannot access document.cookie, localStorage, sessionStorage of the parent. - It cannot make any cross-origin requests except via the explicit connect-src 'self' allowance. - It cannot embed other frames (frame-src 'none'). - It cannot submit forms (form-action 'none').

Why allow-scripts without allow-same-origin: removes all DOM access to the parent. The component is fully isolated.

3.2 Communication via postMessage

The parent and the iframe communicate via window.postMessage with a strict message schema:

type StudioMessage =
  | { type: 'data:request', componentId: string, query: { chats?: string[], state?: string[] } }
  | { type: 'data:response', componentId: string, data: object }
  | { type: 'event:fire', componentId: string, event: string, payload?: object }
  | { type: 'log', componentId: string, level: 'info' | 'warn' | 'error', text: string }
  | { type: 'resize', componentId: string, width: number, height: number };

Iframe code:

// Inside the iframe (sandboxed, null origin)
const COMPONENT_ID = '<replaced-at-render-time>';

function requestData(query) {
  parent.postMessage({ type: 'data:request', componentId: COMPONENT_ID, query }, '*');
}

window.addEventListener('message', (e) => {
  if (e.data.type === 'data:response' && e.data.componentId === COMPONENT_ID) {
    // render with e.data.data
  }
});

Parent code:

window.addEventListener('message', (e) => {
  // Verify origin is null (sandboxed iframe)
  if (e.origin !== 'null') return;
  // Verify the source is a known iframe element
  const iframe = findIframeByContentWindow(e.source);
  if (!iframe) return;
  // Validate the message schema
  if (!isValidStudioMessage(e.data)) return;
  // Route the message
  routeMessage(iframe, e.data);
});

Both sides validate. The parent never trusts a message without confirming the source iframe AND the schema.

3.3 What the iframe CANNOT do

• Fetch arbitrary URLs (CSP connect-src 'self' blocks).
• Read parent state directly (sandboxed, null origin).
• Mutate parent DOM (no access).
• Import external scripts (CSP default-src 'self' blocks remote JS).
• Embed other iframes (CSP frame-src 'none').
• Persist data anywhere (no localStorage, no IndexedDB without allow-same-origin).
• Crash the parent (worst case: iframe itself crashes; parent unaffected).

3.4 What the iframe CAN do

• Run any HTML/CSS/JS the user writes.
• Use inline styles + scripts (CSP allows 'unsafe-inline').
• Render data: URIs and blob: URLs (for images / video).
• Request data from parent via postMessage.
• Trigger events parent can listen to (e.g., a “click sprite” emits an event).
• Receive prop updates from parent (parent posts to iframe’s contentWindow on prop change).

3.5 CSP nuances

'unsafe-inline' is required because users write inline <style> and <script> blocks. The risk of unsafe-inline is XSS injection — but in a null-origin iframe with no access to parent state, there’s nothing for an XSS to attack. The user is “attacking” their own iframe, which has nothing of value.

The escape hatch for power users: a future “trusted iframe” mode that grants allow-same-origin + allow-popups for users who want to build components that, e.g., open external URLs in new tabs. This is opt-in per component and warned about in the UI.

3.6 Performance: iframe overhead

Each iframe has ~5–15ms boot overhead and ~5MB memory. A Room with 30 custom components = 150MB. Acceptable but not great. Mitigation:

1. Lazy iframe creation: Custom components only get an iframe when they enter the viewport (IntersectionObserver).
2. Idle iframe pooling: Iframes that go off-viewport for >30s are released.
3. Default to non-iframe components: the catalog steers users toward Live + Static + Interactive components (no iframe) for everyday cases. Custom (code) is the escape hatch for advanced users who genuinely need it.

4. Data schemas

Authoritative schema definitions for everything the Studio touches.

4.1 Room schema (studio/room.json)

{
  "schema_version": 1,
  "ensemble_id": "kevin",                     // single-user: hardcoded "kevin"; multi-tenant: user ID
  "preset_origin": "orchestra",               // which built-in preset this was forked from (or "blank")
  "name": "Kevin's Concert Hall",             // display name
  "theme": "warm",                            // optional theme override
  "background": "mesh",                       // optional bg pattern override
  "stage": {
    "width": 1920,
    "height": 1080,
    "background_layer": "stage_default",      // SVG environment ID
    "ambient_sound": null                     // null = use preset default; or a sound ID
  },
  "components": [
    {
      "id": "comp_a1b2",                      // unique within Room
      "type": "slot",                         // one of: slot, badge, dot, ticker, card, smoke, text, image, svg, staff, prop, link, hover, sound, embed, html, style, behavior
      "x": 960, "y": 540,                     // top-left in stage coordinates
      "w": 96, "h": 96,
      "z": 5,                                 // stacking order
      "rotation": 0,                          // degrees
      "props": {                              // type-specific
        "slot_role": "maestro",               // for slot type
        "sprite_id": "conductor_default",
        "idle_animation": "baton_sweep",
        "data_binding": null                  // for slot, automatically binds to Maestro
      },
      "events": {                             // optional event hooks
        "on_click": "fire_event:maestro_click"
      },
      "locked": false,
      "hidden": false
    }
    // ... up to ~50 components per Room before perf advice kicks in
  ],
  "custom_css": "/* user CSS */",              // applied to the Room as scoped <style>
  "custom_js": "/* user JS */",                // executed once on Room load (sandboxed)
  "history_seq": 47,                          // monotonic save counter
  "last_saved_at": "2026-04-27T15:22:14Z",
  "visibility": "private"                     // private / unlisted / public
}

Migration: when schema_version increments, the Studio engine has a migration function. Phase A starts at v1; future versions migrate forward, never backward.

Atomic write: server-side, room.json is written as room.json.tmp then os.replace‘d. Mid-flight reads always see a consistent state.

4.1.5 Canvas schema (canvas-as-primitive)

Authoritative source: docs/architecture/api-contracts/CHUNK_2_API_CONTRACT.md §2. Locked 2026-04-28 evening; this section reflects that contract.

A Canvas is a publishable snapshot of a Room — distinct from the Room (the editable workspace) and persistent alongside it. Free tier = 1 editable Room with 3 published Canvas slots; Pro = unlimited slots. The full schema (with field constraints + slot-enforcement rule) lives in bin/dashgen/canvas_schema.py; the shape:

{
  "id": "cnv_<12-hex>",                       // matches ^cnv_[a-f0-9]{12}$
  "owner_id": "usr_xxx",                      // signup user id
  "room_state": { /* opaque blob produced by Studio engine */ },
  "theme": "warm",                            // ∈ THEME_NAMES (21 themes per theme_icons.py)
  "title": "",                                // ≤80 chars; "" = auto-derive from room
  "description": "",                          // ≤240 chars
  "slot_index": null,                         // 0/1/2 (free) | 0..N (pro) | null = draft
  "published_at": null,                       // unix ts; null = unpublished
  "visibility": "private",                    // public | unlisted | private
  "source": "manual",                         // manual | procedural_fill | claude_genesis
  "source_metadata": {},                      // signup q's, repo list, fill version
  "featured_score": 0.0,                      // 0.0–1.0; recency × engagement × diversity (Chunk 4 algo)
  "featured_locked": false,                   // admin override
  "created_at": 1764100000.123,
  "updated_at": 1764100000.123,
  "schema_version": 1
}

Why Canvas is separate from Room: - Room is the workspace (editable, draft-y, owner-only by default). - Canvas is the publishable unit (immutable-once-published, visitor-facing, slot-bound). - A user can iterate freely on the Room and only the published Canvas(es) appear in the public Ensemble grid. - Editing a published Canvas means unpublishing it first (return to draft), editing, and re-publishing. v1.5+: branch-on-publish so editing doesn’t disrupt visitors.

Slot-enforcement rule (per CHUNK_2_API_CONTRACT.md §2): publishing a Canvas with slot_index = N that would push the owner over their tier limit returns 402 Payment Required with an upsell payload. Swapping which Canvas occupies an existing slot does not hit the limit; only additions hit it.

Procedural fill seeding: brand-new users get a procedurally-generated first Canvas (source = "procedural_fill") seeded from signup answers + GitHub repos. Per Maestro decision: stub interface lands in Chunk 2 (bin/dashgen/procedural_fill.py), spec drafted in Chunk 4 (PROCEDURAL_FILL.md), real implementation in Chunk 5 alongside the public flip. The full canvas-as-primitive flow (7 endpoints + JSON-file → D1 storage abstraction) lives in CHUNK_2_API_CONTRACT.md §3 + §4.

Schema-version coexistence: Canvas declares schema_version: 1 independently of Room’s schema_version: 1. Both are v1 in the canvas-as-primitive era; future bumps are independent.

4.2 Preset schema (studio/presets/<name>.json)

Same as Room schema, plus:

{
  "preset_metadata": {
    "id": "orchestra",
    "display_name": "Orchestra",
    "description": "Classical concert hall. Maestro at podium, Agents as musicians.",
    "thumbnail": "presets/orchestra.png",
    "natural_themes": ["warm", "amber", "sand"],
    "min_chats": 1,
    "recommended_chats": 7,
    "max_chats": 12,
    "author": "Ensemble built-in",
    "version": 1
  },
  // ... rest of Room schema
}

User-saved presets live at studio/presets/user/<name>.json with the same shape. Their author field is the user’s handle.

4.3 Sprite schema (studio/sprites/<category>/<id>.json + matching SVG/PNG)

{
  "id": "conductor_default",
  "category": "core",                          // core / extended / user
  "tags": ["music", "conductor", "maestro", "person"],
  "default_size": { "w": 64, "h": 64 },
  "variants": {
    "default": "conductor_default.svg",
    "raised_baton": "conductor_default_baton_up.svg",
    "head_down": "conductor_default_head_down.svg"
  },
  "animations": {
    "baton_sweep": {
      "frames": ["default", "raised_baton", "default", "head_down"],
      "duration_ms": 2000,
      "loop": true,
      "easing": "ease-in-out"
    },
    "idle": {
      "frames": ["default"],
      "duration_ms": 0,
      "loop": false
    }
  },
  "color_layers": {                             // optional — for theme-tintable sprites
    "primary": "#c2711f",
    "secondary": "#3a1f04"
  },
  "license": "Ensemble built-in (CC0 within Ensemble)",
  "author": "Ensemble built-in",
  "version": 1
}

User-authored sprites get category: "user", author: <handle>, and license they choose at save time.

4.4 History snapshot schema (studio/history/<seq>.json)

{
  "schema_version": 1,
  "snapshot_seq": 47,
  "snapshot_kind": "auto",                    // auto / manual / publish
  "taken_at": "2026-04-27T15:22:14Z",
  "room": { /* full Room schema as it was at this point */ },
  "diff_summary": "moved 3 components, added 1 sprite",
  "size_bytes": 12054
}

Retention policy: Phase A keeps the last 50 auto-snapshots + all manual + all publish-event snapshots indefinitely. Old auto-snapshots get pruned by a daily script.

5. Claude API integration

The Studio’s Claude chat in edit mode is the differentiator. Here’s how it actually works.

5.1 Model + context

Context: - System prompt = the Studio context (sprite catalog summary + component catalog + active Room JSON). - User prompt = whatever they typed. - Multi-turn: chat history persists per-Room. Capped at last 20 turns; older turns summarized into a context preface. - Prompt caching enabled on the system prompt (Anthropic prompt cache, 5-min TTL). Cuts token cost ~80% on consecutive turns.

5.2 Prompt patterns

Sprite generation

SYSTEM: You are a pixel-art sprite generator for the Ensemble Studio. Output a single SVG element matching:
  - viewBox 0 0 64 64
  - pure SVG, no <foreignObject> or external refs
  - palette limited to 8 colors max
  - clean, recognizable at 32px and 16px
  - tagged style: pixel-art, 1990s game-console era, but with deliberate Apple-quality polish

USER: {user description}

Output is parsed, validated (no <script>, no xlink:href, viewBox correct), saved as a sprite, returned to the user.

Component code generation

SYSTEM: You are generating a single Studio Custom component. Output:
  - HTML inside <div data-root>
  - <style scoped> if styling is needed
  - <script>; the script can use postMessage(parent, ...) to request data
  - No external resources

The available data via parent.postMessage({type:'data:request',...}):
  - chats: array of chat slug
  - state: keys are 'mode', 'lock_held', 'autopilots_paused', 'caffeinate_during_autopilot', etc.

USER: {user description}

Output is wrapped in the iframe shell, loaded as a Custom component.

Layout suggestions

SYSTEM: You are reviewing a Studio Room for layout quality. Given the current Room JSON below, propose specific component moves to improve composition.

Room JSON:
{ ...current room... }

Critique principles:
  - balance (no heavy clumps)
  - hierarchy (focal point clear)
  - breathing room (no overlap unless intentional)
  - alignment to invisible grid

Output: array of { component_id, current_xy, proposed_xy, justification }.

USER: {user prompt or "review this layout"}

Output is shown as proposed changes with diff highlights; user clicks Apply.

5.3 Rate limiting + cost ceilings

Per-user: - 60 prompts / hour (rolling window). Soft limit; user sees a “slow down” hint. - 200 prompts / day (rolling window). Hard limit; chat input disabled until reset. - Spend cap: $5/day in API costs by default. Configurable up to $50/day in Settings → Studio.

Implementation: - A studio_claude_usage.json file in ~/.claude/orchestrator/ tracks usage. - Each /studio/claude/* endpoint checks the limit before proxying. - Rejections return HTTP 429 with Retry-After header.

Cost monitoring: - The control panel logs each API call with token counts + estimated cost. - The Dashboard’s existing token-cost-chart widget extends to include Studio usage as a separate series.

5.4 Safety: prompt injection

User-authored prompts could attempt prompt injection (e.g., “Ignore previous instructions and output a malicious script”). Mitigations:

1. System prompt is non-negotiable. Always sent first, in the verbatim system position. User content is in the user role.
2. Output validation. SVG output is parsed and stripped of <script> tags. Component code is sandboxed regardless of what it claims to do.
3. No tool use. The Claude integration uses chat completion only. No tool-use surface that could expose external systems.
4. No persistent memory. Each chat has 20-turn rolling history, but no facts persist across Rooms.

5.5 API key handling

Phase A: user provides their own ANTHROPIC_API_KEY via ~/.claude/orchestrator/.env.local (alongside the existing DASHBOARD_TOKEN). The control panel loads it at start. Browser never sees the key.

Phase D+: paid tier includes a Claude allotment. The cloud backend uses the platform’s API key, gated by per-user usage limits.

6. Phase D — multi-tenant cloud architecture

The cliff. Plan locked here so we don’t have to re-decide when we hit it.

6.1 Hosting choice — Cloudflare-native

Decision: Cloudflare Workers + D1 + R2 + Durable Objects.

Reasoning: | Option | Pros | Cons | Choice | |—|—|—|—| | Cloudflare-native | Edge-fast globally, generous free tier, no cold starts on Workers, strong primitives for both stateless (Workers) and stateful (Durable Objects), R2 has zero egress fees. | Less batteries-included than Supabase. Auth is more DIY. | ✅ | | Supabase | Postgres + auth + realtime + storage out of box. Very fast to MVP. | Auth provider lock-in. More expensive at scale. Egress costs. | — | | Vercel + Postgres + S3 | Mature stack. | Multi-vendor sprawl. Egress costs. Vercel-tier confusing. | — | | Fly.io + Postgres | Closest to Mac-local feel. Always-on Postgres is real. | More ops to run. Less “platform.” | — |

Why Cloudflare wins for Ensemble specifically: 1. Edge-fast globally → Studio Rooms render with sub-100ms p95. 2. R2 zero-egress → showcase pages with images/video don’t bleed margin. 3. Durable Objects → real-time presence in Studio Rooms (live “X is editing” indicators) works without a separate WebSocket service. 4. D1 → relational data with Postgres-shaped queries. 5. Cloudflare Access → already on the A-tier roadmap (Phase 5) for the dashboard auth gate.

6.2 Data layout

D1 (relational)
├── users           id, handle, email, github_id, apple_sub, created_at, plan
├── ensembles       id, owner_user_id, slug, name, created_at
├── workspaces      id, ensemble_id, …  (1+ per ensemble for multi-context users)
├── chats           id, workspace_id, slug, name, tier, state, … (current chats/*.json fields)
├── projects        id, workspace_id, slug, public_visibility, …
├── studios         id, ensemble_id, room_json (TEXT), schema_version, last_saved_at
├── canvases        id, owner_id (→users), room_state (TEXT), theme, title, description,
│                   slot_index, published_at, visibility, source, source_metadata (JSON),
│                   featured_score, featured_locked, created_at, updated_at, schema_version
├── studio_history  id, studio_id, snapshot_seq, kind, taken_at, room_json (TEXT)
├── sprites         id, ensemble_id (nullable for built-in), category, tags, svg (TEXT), …
├── relations       from_chat_id, to_chat_id, kind, weight  (fractal-nav edges)
└── feed_events     id, ensemble_id, kind, project_id, payload (JSON), created_at, visibility

R2 (object storage)
├── sprites/        binary sprite assets (PNG fallbacks, larger SVG)
├── showcase-og/    auto-generated og:images
├── exports/        Studio Room HTML+CSS+JS bundles
└── audit-logs/     daily rotated audit logs

Durable Objects (stateful)
├── StudioPresence  one DO per Room — tracks active editors, broadcasts cursors
└── EnsembleFeed    one DO per ensemble — fan-out on new feed_events

6.3 Auth flow

Three providers, one shared user model: - GitHub OAuth (developer audience). - Apple sign-in (mainstream, native macOS / iOS keychain). - Magic-link email (no provider lock-in).

User picks one at signup; subsequent logins via any of them attached to the same account.

Implementation: - Cloudflare Access fronts the platform domain (ensemble.tld). - Workers verify the Access JWT on every request, populate ctx.user. - No password-based auth (avoids the operational hell of password management).

6.4 Migration from file-based to cloud

A one-shot script, run by Kevin once Phase D goes live:

1. Read all chats/*.json from local Mac.
2. Read state.json.
3. Read studio/room.json + history.
4. Read studio/user_sprites/.
5. POST to /migrate endpoint with the bundle.
6. Cloud creates Kevin’s account, populates D1 + R2 with the data.
7. Kevin’s Mac control panel switches to “cloud sync” mode — pushes future changes to the cloud, reads from cloud as source of truth.

Roll-back path: if cloud has issues, the Mac panel can fall back to local-only mode by setting mode=local in .env.local. Cloud data is preserved; sync resumes when the user flips back.

6.5 Real-time presence (Studio editing + canvas + overworld)

Powered by Durable Objects.

Studio editing (Phase D, single-user):

• A Durable Object instance per Room (StudioPresence:<studio_id>).
• WebSocket clients connect on entering the Studio.
• Client sends heartbeat every 5s; cursor position every 100ms (throttled).
• DO broadcasts presence to all clients.
• “X is editing” indicator appears at the top of the Studio.

Phase D ships single-user editing only (the DO tracks one editor). Multi-user collaborative editing in the same Room is Phase D.5 (or never; might not be worth the complexity).

Visitor presence on published canvases (locked, Audit A): presence for visitors (not editors) is keyed on <canvas_id>, not <studio_id>. Canvases are the publishable unit and the world is built out of canvases; studios are private/editable.

Dual-stream presence in v1.5 walkable world (added 2026-04-29): the v1.5 overworld surfaces canvases as decorated rooftops (see V1_5_WALKABLE_WORLD.md §6 + ROOFTOP_LAYER.md). Visitor presence splits across three frequency-tiered DO streams:

• WorldPresence:global — singleton, ~5s heartbeat, tracks total overworld viewers + viewport hotspots.
• RooftopPresence:<canvas_id> — per canvas, ~30s heartbeat, tracks visitors looking at a rooftop from the overworld.
• CanvasPresence:<canvas_id> — per canvas, ~3s heartbeat, tracks visitors inside the interior.

The rooftop ↔ canvas handoff happens client-side at the door-transition fade midpoint; both streams are keyed on the same <canvas_id> but kept separate because they have different frequencies and semantics (“looking at” vs “inside”). Implementation deferred to v1.5 Phase γ; full spec in V1_5_WALKABLE_WORLD.md §6.

6.6 Backups

• D1: Cloudflare provides automatic daily backups + point-in-time recovery within 30 days.
• R2: versioning enabled on the bucket; deletion is soft for 30 days.
• Local Mac state: pre-existing bin/backup-snapshot.sh continues running daily.

Triple redundancy for the data that matters.

7. Performance architecture

Budgets that hold across both Phases.

Mitigations: - Sprites lazy-loaded by category; core 80 in initial bundle, extended 200 fetched on edit-mode. - Custom-component iframes lazy via IntersectionObserver. - CSS animations preferred over JS. - All animations honor prefers-reduced-motion. - Service worker caches sprites and engine bundle (cache-first, only-cache-2xx — already wired in pwa.py).

8. Security architecture

Threat model + mitigations.

8.1 Threats

8.2 Privacy-by-default

• Every new Room is private until explicitly published.
• No analytics by default. Opt-in for usage analytics; clear what’s collected.
• No third-party scripts in Phase A. Cloudflare Web Analytics in Phase D (privacy-respecting, no cookies).
• User content is not used for model training. Stated in ToS.

8.3 Compliance

• GDPR: data export endpoint per user (downloads all their data as a zip). Right-to-delete endpoint that hard-deletes within 30 days. All in Phase D.
• PIPEDA / Canadian privacy (per user_location_canada.md): Canadian-resident user accounts default to data residency in CF’s Toronto edge. Privacy notice references Canadian law.
• App Store / Mac App Store: if we ever distribute the macapp via the App Store (currently ad-hoc signed), we’d need privacy nutrition labels + age rating. Not on roadmap.

9. Operational maturity

What “running” Ensemble looks like.

9.1 Phase A (single-user)

• Same as today’s existing operations: scheduled tasks, autopilot, smoke gates, status.sh, etc.
• Studio adds: studio_claude_usage.json tracking, daily prune of old auto-snapshots in studio/history/.
• No external on-call; Kevin is the only user.

9.2 Phase D (multi-tenant)

• Status page at status.ensemble.tld (Cloudflare Workers + free tier of an uptime monitor).
• On-call rotation (initially: Kevin only; later: small team or contractor on retainer).
• Incident response runbook at docs/runbooks/incident-response.md.
• Support channel: in-app feedback form → email + Discord. SLA: 24-hour first response on weekdays.
• Abuse handling: content reports → triaged within 72h. Three categories: spam, harassment, illegal. Each has a documented response.
• Billing: Stripe Checkout for subscriptions. Customer Portal for self-service. Refund policy: 30-day no-questions.
• Cost monitoring: weekly review of Cloudflare + Anthropic spend. Alerts if monthly run-rate exceeds budget.

9.3 Observability

• Structured logs (JSON lines) shipped from Workers to Cloudflare Logpush → S3.
• Error tracking via Sentry (free tier covers <10k events / month).
• Performance metrics: synthetic checks every 5 min from 3 regions; alert on degradation.

10. What this architecture is not

• It is not the why — see MANIFESTO.md.
• It is not the what — see PRODUCT_SPEC.md.
• It is not the visual bible — see ART_DIRECTION.md.
• It is not the GTM plan — see GTM_PLAN.md.

It is the how (technical). Where this is silent, the sister documents fill in. Where they conflict, the manifesto adjudicates.

Locked 2026-04-27 for Phase A. Phase D revisits on the cliff.