# hruiccc/ruic-foldscreen architecture

> Architecture diagram of the GitHub repository hruiccc/ruic-foldscreen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hruiccc/ruic-foldscreen
- Repository: https://github.com/hruiccc/ruic-foldscreen

## Overview

RuiC-FoldScreen is a local macOS menu-bar app that bends the built-in display as the lid closes. Its main workflow reads lid angle, converts and smooths it into fold parameters, captures desktop frames, renders the perspective/blur effect, and presents it in an overlay; settings also provide presets, tuning, and a permission-free preview. The README documents reconnect and pause behavior plus CLI diagnostics. Wiring for unsampled UI and overlay internals is represented only where documented; optional scripted input is kept separate.

Main entry points: [`Sources/FoldScreen/Core/LiveFold.swift`](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/LiveFold.swift) (Live coordinator), [`Sources/FoldScreen/Render/FoldRenderer.swift`](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/FoldRenderer.swift) (Metal renderer), [`Sources/FoldScreen/UI/SettingsView.swift`](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/SettingsView.swift) (Settings window), [`Sources/FoldScreen/UI/FoldPreview.swift`](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/FoldPreview.swift) (Fold preview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["App control"]
  node_main["App entry<br/>[main.swift]"]
  node_live["Live coordinator<br/>[LiveFold.swift]"]
  node_integration["System integration"]
  node_harness["CLI diagnostics<br/>[Harness.swift]"]
end

subgraph group_inputs["Angle and capture"]
  node_lid["Lid angle source<br/>[LidAngle.swift]"]
  node_scripted["Scripted lid<br/>[LidAngle.swift]"]
  node_capture["Desktop capture"]
end

subgraph group_effect["Fold rendering"]
  node_settings["Fold settings<br/>[FoldSettings.swift]"]
  node_kinematics["Fold kinematics"]
  node_frames["Frame handoff<br/>[FoldRenderer.swift]"]
  node_renderer["Metal renderer<br/>[FoldRenderer.swift]"]
  node_shader["Fold shader<br/>[Fold.metal]"]
  node_artwork["Preview artwork"]
end

subgraph group_interface["User interface"]
  node_overlay["Screen overlay"]
  node_delegate["App delegate<br/>[AppDelegate.swift]"]
  node_settingsui["Settings window<br/>[SettingsView.swift]"]
  node_preview["Fold preview<br/>[FoldPreview.swift]"]
end

node_user(("Mac user"))
node_hid["HID sensor"]
node_screen["Built-in display"]

node_user -->|"launches"| node_main
node_main -->|"starts app"| node_delegate
node_delegate -->|"creates"| node_live
node_delegate -->|"opens"| node_settingsui
node_live -->|"starts and reads"| node_lid
node_lid -->|"reads reports"| node_hid
node_scripted -.->|"supplies angles"| node_lid
node_live -->|"computes closure"| node_kinematics
node_live -->|"uses tuning"| node_settings
node_live -->|"starts and stops"| node_capture
node_capture -->|"captures frames"| node_screen
node_capture -->|"delivers frames"| node_frames
node_live -->|"stores and clears"| node_frames
node_live -->|"configures scene"| node_renderer
node_renderer -->|"reads latest frame"| node_frames
node_renderer -->|"compiles and runs"| node_shader
node_live -->|"controls visibility"| node_overlay
node_overlay -->|"draws effect"| node_renderer
node_settingsui -->|"toggles effect"| node_live
node_settingsui -->|"edits values"| node_settings
node_settingsui -->|"hosts preview"| node_preview
node_preview -->|"builds scene"| node_artwork
node_preview -->|"renders preview"| node_renderer
node_preview -->|"computes closure"| node_kinematics
node_live -->|"uses hotkey"| node_integration
node_main -->|"runs diagnostics"| node_harness
node_harness -->|"exports frames"| node_renderer
node_harness -->|"checks sensor"| node_lid

click node_main "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/main.swift"
click node_live "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/LiveFold.swift"
click node_settings "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/FoldSettings.swift"
click node_kinematics "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/FoldKinematics.swift"
click node_lid "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/LidAngle.swift"
click node_scripted "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/LidAngle.swift"
click node_capture "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Capture/DesktopMirror.swift"
click node_frames "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/FoldRenderer.swift"
click node_renderer "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/FoldRenderer.swift"
click node_shader "https://github.com/hruiccc/ruic-foldscreen/blob/main/Shaders/Fold.metal"
click node_overlay "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/OverlaySurface.swift"
click node_delegate "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/AppDelegate.swift"
click node_settingsui "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/SettingsView.swift"
click node_preview "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/FoldPreview.swift"
click node_artwork "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/PreviewArtwork.swift"
click node_integration "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Support/SystemIntegration.swift"
click node_harness "https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Support/Harness.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_live,node_integration,node_harness,node_user toneBlue
class node_lid,node_scripted,node_capture toneAmber
class node_settings,node_kinematics,node_frames,node_renderer,node_shader,node_artwork toneMint
class node_overlay,node_delegate,node_settingsui,node_preview toneRose
class node_hid,node_screen toneIndigo
```

## Components

### App control

- [App entry](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/main.swift): `Sources/FoldScreen/main.swift`
- [Live coordinator](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/LiveFold.swift): `Sources/FoldScreen/Core/LiveFold.swift`
- [System integration](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Support/SystemIntegration.swift): `Sources/FoldScreen/Support/SystemIntegration.swift`
- [CLI diagnostics](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Support/Harness.swift): `Sources/FoldScreen/Support/Harness.swift`

### Angle and capture

- [Lid angle source](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/LidAngle.swift): `Sources/FoldScreen/Core/LidAngle.swift`
- [Scripted lid](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/LidAngle.swift): `Sources/FoldScreen/Core/LidAngle.swift`
- [Desktop capture](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Capture/DesktopMirror.swift): `Sources/FoldScreen/Capture/DesktopMirror.swift`

### Fold rendering

- [Fold settings](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/FoldSettings.swift): `Sources/FoldScreen/Core/FoldSettings.swift`
- [Fold kinematics](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Core/FoldKinematics.swift): `Sources/FoldScreen/Core/FoldKinematics.swift`
- [Frame handoff](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/FoldRenderer.swift): `Sources/FoldScreen/Render/FoldRenderer.swift`
- [Metal renderer](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/FoldRenderer.swift): `Sources/FoldScreen/Render/FoldRenderer.swift`
- [Fold shader](https://github.com/hruiccc/ruic-foldscreen/blob/main/Shaders/Fold.metal): `Shaders/Fold.metal`
- [Preview artwork](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/PreviewArtwork.swift): `Sources/FoldScreen/Render/PreviewArtwork.swift`

### User interface

- [Screen overlay](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/Render/OverlaySurface.swift): `Sources/FoldScreen/Render/OverlaySurface.swift`
- [App delegate](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/AppDelegate.swift): `Sources/FoldScreen/UI/AppDelegate.swift`
- [Settings window](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/SettingsView.swift): `Sources/FoldScreen/UI/SettingsView.swift`
- [Fold preview](https://github.com/hruiccc/ruic-foldscreen/blob/main/Sources/FoldScreen/UI/FoldPreview.swift): `Sources/FoldScreen/UI/FoldPreview.swift`

### Other components

- **Mac user**
- **HID sensor**
- **Built-in display**

## Connections

- Mac user → App entry: launches
- App entry → App delegate: starts app
- App delegate → Live coordinator: creates
- App delegate → Settings window: opens
- Live coordinator → Lid angle source: starts and reads
- Lid angle source → HID sensor: reads reports
- Scripted lid → Lid angle source: supplies angles
- Live coordinator → Fold kinematics: computes closure
- Live coordinator → Fold settings: uses tuning
- Live coordinator → Desktop capture: starts and stops
- Desktop capture → Built-in display: captures frames
- Desktop capture → Frame handoff: delivers frames
- Live coordinator → Frame handoff: stores and clears
- Live coordinator → Metal renderer: configures scene
- Metal renderer → Frame handoff: reads latest frame
- Metal renderer → Fold shader: compiles and runs
- Live coordinator → Screen overlay: controls visibility
- Screen overlay → Metal renderer: draws effect
- Settings window → Live coordinator: toggles effect
- Settings window → Fold settings: edits values
- Settings window → Fold preview: hosts preview
- Fold preview → Preview artwork: builds scene
- Fold preview → Metal renderer: renders preview
- Fold preview → Fold kinematics: computes closure
- Live coordinator → System integration: uses hotkey
- App entry → CLI diagnostics: runs diagnostics
- CLI diagnostics → Metal renderer: exports frames
- CLI diagnostics → Lid angle source: checks sensor