ADR 0003: Desktop App Scope
Accepted
Status
Section titled “Status”Accepted
2026-07-15
Context
Section titled “Context”The Cosella product has a web dashboard and a desktop app. The question was whether the desktop app should embed the full dashboard, be a lightweight overlay-only tool, or something in between.
Decision
Section titled “Decision”The desktop app consists of exactly two window surfaces:
- Overlay window — frameless, transparent, always-on-top live call coaching UI
- Settings window — native OS chrome for native-only preferences (audio device, stealth, updates)
The desktop app does NOT embed any dashboard features. For dashboard-class functionality (contacts, payments, team, call history), the desktop deep-links to the web dashboard via shell.openExternal().
Two in-scope surfaces that live inside the overlay window:
- Sign-in / identity flow — rendered before a workspace exists
- Idle / between-calls state — rendered when no call is active
Consequences
Section titled “Consequences”src/is organized with overlay as primary, settings as secondary- No
WebContentsView, no iframe, no feature parity with web - Capability routing consumes the same
@cosella/auth+@cosella/permissionspackages - Tiny route tree (5 overlay routes, 5 settings routes)
- Deep-link-vs-embed is resolved: always deep-link out