# kalkman-code/beamer architecture

> Architecture diagram of the GitHub repository kalkman-code/beamer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kalkman-code/beamer
- Repository: https://github.com/kalkman-code/beamer

## Overview

Beamer shares keyboard, pointer and clipboard input between paired Macs, Windows PCs and Linux machines over a local network. The main user flow is to pair machines, configure crossing directions and edges, then cross by pushing the pointer or using a shortcut; the receiving machine injects the input. Shared modules implement pairing, wire protocol, peer state, crossing behavior and synchronized settings, while desktop apps provide platform-specific UI and input handling. The README documents the user workflow; source-index references support several internal links, but unsampled platform code limits detail on implementation relationships.

Main entry points: [`mac_app/kvm_bridge_app.py`](https://github.com/kalkman-code/beamer/blob/main/mac_app/kvm_bridge_app.py) (macOS app), [`core/crossing_state.py`](https://github.com/kalkman-code/beamer/blob/main/core/crossing_state.py) (Crossing state), [`win_app/kvm_bridge_win.py`](https://github.com/kalkman-code/beamer/blob/main/win_app/kvm_bridge_win.py) (Windows and Linux app), [`core/receiver.py`](https://github.com/kalkman-code/beamer/blob/main/core/receiver.py) (Connection responder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Desktop apps"]
  node_mac_app["macOS app<br/>[kvm_bridge_app.py]"]
  node_win_app["Windows and Linux app<br/>[kvm_bridge_win.py]"]
end

subgraph group_crossing["Crossing and input"]
  node_mac_cross["macOS crossing<br/>[crossing.py]"]
  node_mac_motion["Pointer motion<br/>[motion.py]"]
  node_cross_state["Crossing state<br/>[crossing_state.py]"]
  node_ways["Edge and zone rules<br/>[ways.py]"]
  node_return_edge["Return-edge model<br/>[return_edge.py]"]
  node_keytable["Key mappings<br/>[keytable.py]"]
end

subgraph group_network["Pairing and links"]
  node_pairing["LAN pairing<br/>[pairing.py]"]
  node_peerlist["Paired machines<br/>[peerlist.py]"]
  node_link["Connection initiator<br/>[link.py]"]
  node_receiver["Connection responder<br/>[receiver.py]"]
  node_protocol["Wire protocol<br/>[protocol.py]"]
end

subgraph group_settings["Settings and design"]
  node_profiles["Machine profiles<br/>[profiles.py]"]
  node_settings_sync["Settings sync<br/>[settings_sync.py]"]
  node_effects["Crossing effects<br/>[effects.py]"]
  node_i18n["Translations<br/>[i18n.py]"]
  node_theme["macOS theme<br/>[theme.py]"]
  node_tokens["Design tokens<br/>[tokens.py]"]
end

node_user(("User"))

node_user -->|"configures"| node_mac_app
node_user -->|"configures"| node_win_app
node_mac_app -.->|"starts pairing"| node_pairing
node_win_app -.->|"starts pairing"| node_pairing
node_pairing -->|"stores peer"| node_peerlist
node_mac_app -.->|"opens link"| node_link
node_link -->|"uses wire format"| node_protocol
node_receiver -->|"uses wire format"| node_protocol
node_mac_app -->|"runs responder"| node_receiver
node_win_app -->|"runs responder"| node_receiver
node_mac_app -->|"handles crossing"| node_mac_cross
node_mac_cross -->|"uses edge model"| node_return_edge
node_mac_app -->|"updates state"| node_cross_state
node_cross_state -->|"uses crossing rules"| node_ways
node_cross_state -->|"loads profiles"| node_profiles
node_cross_state -->|"encodes state"| node_protocol
node_cross_state -->|"uses edge model"| node_return_edge
node_mac_app -->|"uses key mappings"| node_keytable
node_mac_app -->|"handles pointer motion"| node_mac_motion
node_receiver -->|"reads peer state"| node_peerlist
node_profiles -->|"reads peers"| node_peerlist
node_profiles -->|"uses sync state"| node_settings_sync
node_settings_sync -->|"validates messages"| node_protocol
node_settings_sync -->|"syncs design settings"| node_effects
node_mac_app -->|"renders effects"| node_effects
node_mac_app -->|"uses translations"| node_i18n
node_theme -->|"loads palettes"| node_tokens
node_user -->|"crosses or shortcuts"| node_mac_app
node_mac_app -->|"sends input and clipboard"| node_win_app
node_win_app -->|"sends input and clipboard"| node_mac_app

click node_mac_app "https://github.com/kalkman-code/beamer/blob/main/mac_app/kvm_bridge_app.py"
click node_win_app "https://github.com/kalkman-code/beamer/blob/main/win_app/kvm_bridge_win.py"
click node_mac_cross "https://github.com/kalkman-code/beamer/blob/main/mac_app/crossing.py"
click node_mac_motion "https://github.com/kalkman-code/beamer/blob/main/mac_app/motion.py"
click node_cross_state "https://github.com/kalkman-code/beamer/blob/main/core/crossing_state.py"
click node_ways "https://github.com/kalkman-code/beamer/blob/main/core/ways.py"
click node_return_edge "https://github.com/kalkman-code/beamer/blob/main/core/return_edge.py"
click node_keytable "https://github.com/kalkman-code/beamer/blob/main/core/keytable.py"
click node_pairing "https://github.com/kalkman-code/beamer/blob/main/core/pairing.py"
click node_peerlist "https://github.com/kalkman-code/beamer/blob/main/core/peerlist.py"
click node_link "https://github.com/kalkman-code/beamer/blob/main/core/link.py"
click node_receiver "https://github.com/kalkman-code/beamer/blob/main/core/receiver.py"
click node_protocol "https://github.com/kalkman-code/beamer/blob/main/core/protocol.py"
click node_profiles "https://github.com/kalkman-code/beamer/blob/main/core/profiles.py"
click node_settings_sync "https://github.com/kalkman-code/beamer/blob/main/core/settings_sync.py"
click node_effects "https://github.com/kalkman-code/beamer/blob/main/core/effects.py"
click node_i18n "https://github.com/kalkman-code/beamer/blob/main/core/i18n.py"
click node_theme "https://github.com/kalkman-code/beamer/blob/main/theme.py"
click node_tokens "https://github.com/kalkman-code/beamer/blob/main/tokens.py"

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_mac_app,node_win_app,node_user toneBlue
class node_mac_cross,node_mac_motion,node_cross_state,node_ways,node_return_edge,node_keytable toneAmber
class node_pairing,node_peerlist,node_link,node_receiver,node_protocol toneMint
class node_profiles,node_settings_sync,node_effects,node_i18n,node_theme,node_tokens toneRose
```

## Components

### Desktop apps

- [macOS app](https://github.com/kalkman-code/beamer/blob/main/mac_app/kvm_bridge_app.py): `mac_app/kvm_bridge_app.py`
- [Windows and Linux app](https://github.com/kalkman-code/beamer/blob/main/win_app/kvm_bridge_win.py): `win_app/kvm_bridge_win.py`

### Crossing and input

- [macOS crossing](https://github.com/kalkman-code/beamer/blob/main/mac_app/crossing.py): `mac_app/crossing.py`
- [Pointer motion](https://github.com/kalkman-code/beamer/blob/main/mac_app/motion.py): `mac_app/motion.py`
- [Crossing state](https://github.com/kalkman-code/beamer/blob/main/core/crossing_state.py): `core/crossing_state.py`
- [Edge and zone rules](https://github.com/kalkman-code/beamer/blob/main/core/ways.py): `core/ways.py`
- [Return-edge model](https://github.com/kalkman-code/beamer/blob/main/core/return_edge.py): `core/return_edge.py`
- [Key mappings](https://github.com/kalkman-code/beamer/blob/main/core/keytable.py): `core/keytable.py`

### Pairing and links

- [LAN pairing](https://github.com/kalkman-code/beamer/blob/main/core/pairing.py): `core/pairing.py`
- [Paired machines](https://github.com/kalkman-code/beamer/blob/main/core/peerlist.py): `core/peerlist.py`
- [Connection initiator](https://github.com/kalkman-code/beamer/blob/main/core/link.py): `core/link.py`
- [Connection responder](https://github.com/kalkman-code/beamer/blob/main/core/receiver.py): `core/receiver.py`
- [Wire protocol](https://github.com/kalkman-code/beamer/blob/main/core/protocol.py): `core/protocol.py`

### Settings and design

- [Machine profiles](https://github.com/kalkman-code/beamer/blob/main/core/profiles.py): `core/profiles.py`
- [Settings sync](https://github.com/kalkman-code/beamer/blob/main/core/settings_sync.py): `core/settings_sync.py`
- [Crossing effects](https://github.com/kalkman-code/beamer/blob/main/core/effects.py): `core/effects.py`
- [Translations](https://github.com/kalkman-code/beamer/blob/main/core/i18n.py): `core/i18n.py`
- [macOS theme](https://github.com/kalkman-code/beamer/blob/main/theme.py): `theme.py`
- [Design tokens](https://github.com/kalkman-code/beamer/blob/main/tokens.py): `tokens.py`

### Other components

- **User**

## Connections

- User → macOS app: configures (evidence: `README.md`)
- User → Windows and Linux app: configures (evidence: `README.md`)
- macOS app → LAN pairing: starts pairing (evidence: `mac_app/kvm_bridge_app.py`)
- Windows and Linux app → LAN pairing: starts pairing (evidence: `win_app/kvm_bridge_win.py`)
- LAN pairing → Paired machines: stores peer (evidence: `core/peerlist.py`)
- macOS app → Connection initiator: opens link
- Connection initiator → Wire protocol: uses wire format (evidence: `core/link.py`)
- Connection responder → Wire protocol: uses wire format (evidence: `core/receiver.py`)
- macOS app → Connection responder: runs responder (evidence: `mac_app/kvm_bridge_app.py`)
- Windows and Linux app → Connection responder: runs responder (evidence: `win_app/kvm_bridge_win.py`)
- macOS app → macOS crossing: handles crossing (evidence: `mac_app/kvm_bridge_app.py`)
- macOS crossing → Return-edge model: uses edge model (evidence: `mac_app/crossing.py`)
- macOS app → Crossing state: updates state (evidence: `mac_app/kvm_bridge_app.py`)
- Crossing state → Edge and zone rules: uses crossing rules (evidence: `core/crossing_state.py`)
- Crossing state → Machine profiles: loads profiles (evidence: `core/crossing_state.py`)
- Crossing state → Wire protocol: encodes state (evidence: `core/crossing_state.py`)
- Crossing state → Return-edge model: uses edge model (evidence: `core/crossing_state.py`)
- macOS app → Key mappings: uses key mappings
- macOS app → Pointer motion: handles pointer motion (evidence: `mac_app/kvm_bridge_app.py`)
- Connection responder → Paired machines: reads peer state (evidence: `core/receiver.py`)
- Machine profiles → Paired machines: reads peers (evidence: `core/profiles.py`)
- Machine profiles → Settings sync: uses sync state (evidence: `core/profiles.py`)
- Settings sync → Wire protocol: validates messages (evidence: `core/settings_sync.py`)
- Settings sync → Crossing effects: syncs design settings (evidence: `core/settings_sync.py`)
- macOS app → Crossing effects: renders effects (evidence: `mac_app/kvm_bridge_app.py`)
- macOS app → Translations: uses translations (evidence: `mac_app/kvm_bridge_app.py`)
- macOS theme → Design tokens: loads palettes (evidence: `theme.py`)
- User → macOS app: crosses or shortcuts (evidence: `README.md`)
- macOS app → Windows and Linux app: sends input and clipboard (evidence: `README.md`)
- Windows and Linux app → macOS app: sends input and clipboard (evidence: `README.md`)