# maxpoww/golem architecture

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

- Interactive diagram: https://gitdiagram.com/maxpoww/golem
- Repository: https://github.com/maxpoww/golem

## Overview

Golem OS is a NixOS desktop distribution, with a companion desktop daemon for phone-based input and screen mirroring. The main user journey is to prepare a machine through the installer, detect hardware and select configuration, then boot into the configured desktop; a phone can separately pair with the running daemon and send input or request mirroring. The graph includes documented desktop surfaces, but their implementation wiring is not established by the sampled source. Installer and hardware-detection details are likewise represented conservatively where source excerpts were unavailable.

Main entry points: [`golem-connectd/src/main.rs`](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/main.rs) (Connect Daemon), [`system/home/home.nix`](https://github.com/maxpoww/golem/blob/main/system/home/home.nix) (Home Environment), [`flake.nix`](https://github.com/maxpoww/golem/blob/main/flake.nix) (NixOS Flake), [`system/configuration.nix`](https://github.com/maxpoww/golem/blob/main/system/configuration.nix) (System Profile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_distribution["OS Distribution"]
  node_flake["NixOS Flake<br/>[flake.nix]"]
  node_system["System Profile<br/>[configuration.nix]"]
  node_host["Machine Profiles"]
  node_hardware["Hardware Modules<br/>[hardware.nix]"]
end

subgraph group_install["Installation"]
  node_preinstall["Preinstall Assessment"]
  node_evidence["Hardware Evidence<br/>[evidence.nix]"]
  node_decision["Hardware Decision<br/>[decide.nix]"]
  node_installer["Installer Image"]
end

subgraph group_desktop["Desktop Environment"]
  node_home["Home Environment<br/>[home.nix]"]
  node_apps["Golem Apps<br/>[golem-apps.nix]"]
  node_waverunner["Dock Launcher"]
  node_notifications["Notification Bridge<br/>[inject.js]"]
end

subgraph group_connect["Phone Connectivity"]
  node_connectd["Connect Daemon<br/>[main.rs]"]
  node_packet["Packet Protocol<br/>[packet.rs]"]
  node_crypto["Pairing Security<br/>[crypto.rs]"]
  node_mousepad["Mousepad Mapping<br/>[mousepad.rs]"]
  node_gamepad["Gamepad Mapping<br/>[gamepad.rs]"]
  node_input["Wayland Input<br/>[input.rs]"]
  node_uinput["Virtual Gamepad<br/>[uinput.rs]"]
  node_mirror["Screen Mirroring<br/>[mirror.rs]"]
end

node_user(("User"))
node_machine(("Target Machine"))
node_phone(("Phone"))
node_wayland["Wayland Compositor"]
node_kernel["Linux Input"]
node_adb["ADB and scrcpy"]

node_user -->|"starts install"| node_installer
node_machine -->|"provides facts"| node_evidence
node_preinstall -->|"collects"| node_evidence
node_preinstall -->|"selects configuration"| node_decision
node_installer -->|"installs system"| node_flake
node_user -->|"builds or boots"| node_flake
node_flake -->|"selects profile"| node_host
node_flake -->|"builds profile"| node_system
node_system -->|"configures hardware"| node_hardware
node_system -->|"configures home"| node_home
node_home -->|"enables apps"| node_apps
node_home -->|"configures surface"| node_waverunner
node_home -->|"includes bridge"| node_notifications
node_phone -->|"pairs and sends requests"| node_connectd
node_connectd -->|"parses and frames"| node_packet
node_connectd -->|"verifies pairing"| node_crypto
node_connectd -->|"translates requests"| node_mousepad
node_connectd -->|"translates requests"| node_gamepad
node_mousepad -->|"produces events"| node_input
node_input -->|"injects input"| node_wayland
node_connectd -->|"dispatches gamepad events"| node_uinput
node_uinput -->|"writes device events"| node_kernel
node_connectd -->|"handles mirror requests"| node_mirror
node_mirror -->|"starts or stops mirroring"| node_adb
node_phone -.->|"provides USB device"| node_adb

click node_flake "https://github.com/maxpoww/golem/blob/main/flake.nix"
click node_system "https://github.com/maxpoww/golem/blob/main/system/configuration.nix"
click node_host "https://github.com/maxpoww/golem/tree/main/hosts"
click node_hardware "https://github.com/maxpoww/golem/blob/main/system/hardware.nix"
click node_preinstall "https://github.com/maxpoww/golem/tree/main/Installer/preinstall"
click node_evidence "https://github.com/maxpoww/golem/blob/main/Installer/preinstall/evidence.nix"
click node_decision "https://github.com/maxpoww/golem/blob/main/Installer/preinstall/decide.nix"
click node_installer "https://github.com/maxpoww/golem/blob/main/Installer/preinstall/iso-image-golem.nix"
click node_home "https://github.com/maxpoww/golem/blob/main/system/home/home.nix"
click node_apps "https://github.com/maxpoww/golem/blob/main/system/golem-apps.nix"
click node_waverunner "https://github.com/maxpoww/golem/blob/main/system/home/waverunner-packages.nix"
click node_notifications "https://github.com/maxpoww/golem/blob/main/system/home/notification-fix/inject.js"
click node_connectd "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/main.rs"
click node_packet "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/packet.rs"
click node_crypto "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/crypto.rs"
click node_mousepad "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/mousepad.rs"
click node_gamepad "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/gamepad.rs"
click node_input "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/input.rs"
click node_uinput "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/uinput.rs"
click node_mirror "https://github.com/maxpoww/golem/blob/main/golem-connectd/src/mirror.rs"

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_flake,node_system,node_host,node_hardware,node_user toneBlue
class node_preinstall,node_evidence,node_decision,node_installer toneAmber
class node_home,node_apps,node_waverunner,node_notifications toneMint
class node_connectd,node_packet,node_crypto,node_mousepad,node_gamepad,node_input,node_uinput,node_mirror toneRose
class node_machine,node_phone,node_wayland,node_kernel,node_adb toneIndigo
```

## Components

### OS Distribution

- [NixOS Flake](https://github.com/maxpoww/golem/blob/main/flake.nix): `flake.nix`
- [System Profile](https://github.com/maxpoww/golem/blob/main/system/configuration.nix): `system/configuration.nix`
- [Machine Profiles](https://github.com/maxpoww/golem/tree/main/hosts): `hosts`
- [Hardware Modules](https://github.com/maxpoww/golem/blob/main/system/hardware.nix): `system/hardware.nix`

### Installation

- [Preinstall Assessment](https://github.com/maxpoww/golem/tree/main/Installer/preinstall): `Installer/preinstall`
- [Hardware Evidence](https://github.com/maxpoww/golem/blob/main/Installer/preinstall/evidence.nix): `Installer/preinstall/evidence.nix`
- [Hardware Decision](https://github.com/maxpoww/golem/blob/main/Installer/preinstall/decide.nix): `Installer/preinstall/decide.nix`
- [Installer Image](https://github.com/maxpoww/golem/blob/main/Installer/preinstall/iso-image-golem.nix): `Installer/preinstall/iso-image-golem.nix`

### Desktop Environment

- [Home Environment](https://github.com/maxpoww/golem/blob/main/system/home/home.nix): `system/home/home.nix`
- [Golem Apps](https://github.com/maxpoww/golem/blob/main/system/golem-apps.nix): `system/golem-apps.nix`
- [Dock Launcher](https://github.com/maxpoww/golem/blob/main/system/home/waverunner-packages.nix): `system/home/waverunner-packages.nix`
- [Notification Bridge](https://github.com/maxpoww/golem/blob/main/system/home/notification-fix/inject.js): `system/home/notification-fix/inject.js`

### Phone Connectivity

- [Connect Daemon](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/main.rs): `golem-connectd/src/main.rs`
- [Packet Protocol](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/packet.rs): `golem-connectd/src/packet.rs`
- [Pairing Security](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/crypto.rs): `golem-connectd/src/crypto.rs`
- [Mousepad Mapping](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/mousepad.rs): `golem-connectd/src/mousepad.rs`
- [Gamepad Mapping](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/gamepad.rs): `golem-connectd/src/gamepad.rs`
- [Wayland Input](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/input.rs): `golem-connectd/src/input.rs`
- [Virtual Gamepad](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/uinput.rs): `golem-connectd/src/uinput.rs`
- [Screen Mirroring](https://github.com/maxpoww/golem/blob/main/golem-connectd/src/mirror.rs): `golem-connectd/src/mirror.rs`

### Other components

- **User**
- **Target Machine**
- **Phone**
- **Wayland Compositor**
- **Linux Input**
- **ADB and scrcpy**

## Connections

- User → Installer Image: starts install
- Target Machine → Hardware Evidence: provides facts
- Preinstall Assessment → Hardware Evidence: collects
- Preinstall Assessment → Hardware Decision: selects configuration
- Installer Image → NixOS Flake: installs system
- User → NixOS Flake: builds or boots
- NixOS Flake → Machine Profiles: selects profile
- NixOS Flake → System Profile: builds profile
- System Profile → Hardware Modules: configures hardware
- System Profile → Home Environment: configures home
- Home Environment → Golem Apps: enables apps
- Home Environment → Dock Launcher: configures surface
- Home Environment → Notification Bridge: includes bridge
- Phone → Connect Daemon: pairs and sends requests
- Connect Daemon → Packet Protocol: parses and frames
- Connect Daemon → Pairing Security: verifies pairing
- Connect Daemon → Mousepad Mapping: translates requests
- Connect Daemon → Gamepad Mapping: translates requests
- Mousepad Mapping → Wayland Input: produces events
- Wayland Input → Wayland Compositor: injects input
- Connect Daemon → Virtual Gamepad: dispatches gamepad events
- Virtual Gamepad → Linux Input: writes device events
- Connect Daemon → Screen Mirroring: handles mirror requests
- Screen Mirroring → ADB and scrcpy: starts or stops mirroring
- Phone → ADB and scrcpy: provides USB device