Eve library

ADR-0006: Bellona Control Room Placement

ADR

Revision 1

On this page
  • Status: Accepted
  • Date: 2026-04-22
  • Authors: Bellona Remote Control Working Group, Codex
  • Reviewers: Bellona, Yemaya, Oshun Platform, Oshun Security

Context and Problem Statement#

180.C.12.01 decides whether the MVP Control Room lives in a new apps/bellona/control-room app or inside an existing Yemaya Studio app.

The Control Room is the operator surface for remote device identity, sessions, command timelines, approvals, stream/screenshot state, pause/stop, takeover, degraded states, audit evidence, and replay. It is not a normal production workspace page. Its state must be gateway-backed and protocol-owned so the UI cannot bypass pairing, policy, approval, audit, or evidence capture.

Existing research already sets the boundary:

  • 180.C.02.07 audited apps/yemaya/studio-web and apps/yemaya/studio-desktop. Both provide useful React, Playwright, Electron, IPC, and native-shell patterns, but neither models remote device/session, approval, stream, command timeline, emergency stop, or audit authority.
  • ADR-0001 chooses a standalone Bellona Remote Gateway and Remote Host, and rejects making Yemaya Studio the privileged remote-control authority.
  • ADR-0005 names a Bellona Control Room MVP as part of the MVP alpha artifact.
  • The compatibility matrix already describes a browser-first Bellona Control Room, with a desktop wrapper deferred to native distribution needs.

Decision Drivers#

  • Preserve Bellona ownership of remote-control authority, protocol state, audit, stream visibility, and operator intervention.
  • Keep privileged remote operations separate from Yemaya project/workspace stores and Electron IPC.
  • Ship the MVP as a browser-first operational app with Playwright coverage.
  • Reuse existing Yemaya UI and desktop patterns where they are implementation references, not authority boundaries.
  • Leave a clean path for future Yemaya deep links, project context, native packaging, multi-monitor layouts, and picture-in-picture stream viewing.

Considered Options#

Option 1: Create apps/bellona/control-room#

Create a Bellona-owned web application for the Control Room MVP. It consumes Remote Gateway APIs/WebSockets, imports libs/bellona/remote-protocol contracts, and owns device/session/timeline/approval/stream/replay state.

This option is chosen.

Option 2: Add Control Room Routes to apps/yemaya/studio-web#

Yemaya Studio Web already has Vite, React, guarded routes, Zustand stores, API helpers, and Playwright coverage.

This option is rejected for MVP placement. Reusing its patterns is useful, but putting the Control Room inside the production workspace shell couples privileged operator state to project pages and existing studio stores. Yemaya can later deep-link into Bellona sessions with project context.

Option 3: Add Control Room Views to apps/yemaya/studio-desktop#

Yemaya Studio Desktop already has Electron packaging, secure preload defaults, native menus, tray behavior, window layout, fullscreen, multi-monitor, and picture-in-picture patterns.

This option is rejected for MVP placement. Those native affordances are useful later, but the MVP Control Room should not depend on Electron IPC or a desktop project shell. A desktop wrapper can load or embed the Bellona Control Room once the web core is stable.

Decision Outcome#

The MVP Control Room will be scaffolded in apps/bellona/control-room at 180.C.12.02.

It will be a browser-first Bellona app. The primary app surface should behave like an operational workspace, not a marketing page: dense, scannable, status-first, low chrome, and organized around device state, session timeline, approval state, stream/screenshot evidence, and emergency operator actions.

The initial implementation must:

  • consume Remote Gateway state instead of Yemaya project stores
  • import protocol contracts from libs/bellona/remote-protocol
  • keep every command path gateway-backed and policy/audit visible
  • add Playwright coverage for the first scaffolded route and later UI states
  • avoid adding privileged execution through the renderer or Electron IPC
  • remain embeddable later by sharing UI/domain packages rather than forking separate web and desktop Control Room implementations

Reuse Rules#

Reuse from apps/yemaya/studio-web:

  • Vite/React app shape
  • route guards and lazy loading patterns
  • Zustand store organization
  • API helper conventions
  • Playwright desktop/mobile viewport coverage

Reuse from apps/yemaya/studio-desktop later:

  • secure Electron preload and IPC inventory patterns
  • native packaging/update/signing workflow
  • deep links
  • multi-window, multi-monitor, fullscreen, and picture-in-picture patterns
  • OS permission diagnostic UX patterns

Do not reuse:

  • Yemaya project/workspace stores as Control Room session authority
  • desktop engine bridge IPC as remote-control command execution
  • Electron renderer privileges for Bellona remote actions
  • separate web and desktop Control Room implementations

Consequences#

  • 180.C.12.02 must scaffold apps/bellona/control-room, not a Yemaya route.
  • Later Yemaya work may link to or embed Control Room views, but the canonical session, command, stream, approval, audit, and replay state remains Bellona gateway-backed.
  • Playwright coverage belongs with the Bellona Control Room app from the first UI scaffold.
  • Native desktop distribution remains a later wrapper concern after the protocol-backed web core is working.