Skip to content

architecture.md

Latest commit

 

History

History
42 lines (29 loc) · 2.45 KB

architecture.md

File metadata and controls

42 lines (29 loc) · 2.45 KB
Raw

Architecture

Broken Screen separates the control surface from the display safety engine.

flowchart LR
  UI["Tauri web UI"] --> Commands["Typed Tauri commands"]
  Commands --> Engine["Rust safety engine"]
  Engine --> Inventory["Core Graphics inventory"]
  Engine --> Classifier["CoreDisplay classification"]
  Engine --> Switch["App-scoped display configuration"]
  Engine --> Preferences["Local automation preference"]
  Engine --> Watchdog["Independent recovery process"]
Loading

Control surface

The TypeScript frontend renders reported display state and invokes a small command boundary. It does not decide whether a display can be disconnected.

Safety engine

Rust owns classification, reconciliation, persistence, and restoration. Protection can begin only when an active, online, confirmed physical external display exists. Virtual and unknown displays cannot authorize the initial topology change.

Recovery

Display changes use app scope so WindowServer can unwind them on process loss. Before disabling the internal panel, the engine starts a separate watchdog that restores it if the parent process disappears. Normal shutdown and automation disable also restore managed state.

Platform boundary

The engine dynamically resolves the private macOS symbol rather than assuming availability. Unsupported platforms and systems without the symbol fail closed. No display-changing implementation is compiled for non-macOS targets.

Rust module map

  • src-tauri/src/lib.rs wires the modules together and exposes the application and watchdog entry points.
  • src-tauri/src/models.rs defines the shared display classifications and command response types.
  • src-tauri/src/policy.rs reduces display inventory into a pure, cross-platform safety decision and owns its unit tests.
  • src-tauri/src/display.rs owns display discovery, physical/virtual classification, and the macOS configuration boundary.
  • src-tauri/src/safety.rs owns On/Off state, safety rules, reconciliation, preferences, lid state, and restoration.
  • src-tauri/src/watchdog.rs owns the independent recovery child process and crash-response behavior.
  • src-tauri/src/app.rs owns Tauri commands, menu-bar behavior, launch at login, and window lifecycle.

Dependencies flow in one direction: shared models feed display integration, display integration supports the watchdog and safety engine, and the app layer invokes those lower-level components. UI code never calls private macOS APIs directly.