# ADR-0006: Bellona Control Room Placement

- **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.
