# barredewe/snowfall architecture

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

- Interactive diagram: https://gitdiagram.com/barredewe/snowfall
- Repository: https://github.com/barredewe/snowfall

## Overview

Snowfall is a macOS menubar app that displays interactive, GPU-rendered snow across connected displays. The main workflow creates a transparent overlay per screen, uses a Metal view controller to manage rendering and lifecycle, and has a renderer update particles before submitting frames to Metal. Users adjust presets and effects in the menubar settings, which persist locally. The README documents window collisions, mouse and wind effects, multi-monitor support, and adaptive rendering; profiling support is also represented. Some subsystem links rely on README statements or the source index because not all implementation files were sampled.

Main entry points: [`SnowfallApp/Sources/Common/SnowRenderer.swift`](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowRenderer.swift) (Frame Renderer), [`SnowfallApp/Sources/Views/MetalSnowViewController.swift`](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Views/MetalSnowViewController.swift) (Overlay Controller), [`SnowfallApp/Sources/Views/MenuBarSettings.swift`](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Views/MenuBarSettings.swift) (Menubar Controls), [`SnowfallApp/Sources/SnowfallApp.swift`](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/SnowfallApp.swift) (App Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and Settings"]
  node_app["App Lifecycle<br/>[SnowfallApp.swift]"]
  node_settings_ui["Menubar Controls"]
  node_settings["Preferences<br/>[Settings.swift]"]
end

subgraph group_overlay["Desktop Overlay"]
  node_overlay_controller["Overlay Controller"]
  node_render_policy["Render Policy"]
end

subgraph group_simulation["Snow Simulation"]
  node_simulation["Particle Simulation"]
  node_snowflake["Particle Data<br/>[Snowflake.swift]"]
  node_window_info["Window Detection<br/>[WindowInfo.swift]"]
end

subgraph group_rendering["Metal Rendering"]
  node_renderer["Frame Renderer<br/>[SnowRenderer.swift]"]
  node_shader["Metal Shaders<br/>[SnowShader.metal]"]
  node_performance_trace["Performance Trace"]
end

node_user(("User"))
node_macos["macOS Window APIs"]

node_user -->|"adjusts settings"| node_settings_ui
node_app -->|"presents menu"| node_settings_ui
node_settings_ui -->|"updates and saves"| node_settings
node_app -->|"creates per screen"| node_overlay_controller
node_overlay_controller -->|"delegates frames"| node_renderer
node_overlay_controller -->|"sets display policy"| node_render_policy
node_renderer -->|"reads preferences"| node_settings
node_renderer -->|"updates particles"| node_simulation
node_simulation -->|"initializes particles"| node_snowflake
node_renderer -->|"queries window bounds"| node_window_info
node_window_info -->|"queries window list"| node_macos
node_renderer -->|"uses Metal kernels"| node_shader
node_renderer -->|"records GPU frames"| node_performance_trace

click node_app "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/SnowfallApp.swift"
click node_settings_ui "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Views/MenuBarSettings.swift"
click node_settings "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/Settings.swift"
click node_overlay_controller "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Views/MetalSnowViewController.swift"
click node_render_policy "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowRenderPolicy.swift"
click node_renderer "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowRenderer.swift"
click node_shader "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowShader.metal"
click node_performance_trace "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowPerformanceTrace.swift"
click node_simulation "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowSimulation.swift"
click node_snowflake "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/Snowflake.swift"
click node_window_info "https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/WindowInfo.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_app,node_settings_ui,node_settings,node_user toneBlue
class node_overlay_controller,node_render_policy toneAmber
class node_simulation,node_snowflake,node_window_info,node_macos toneMint
class node_renderer,node_shader,node_performance_trace toneRose
```

## Components

### App and Settings

- [App Lifecycle](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/SnowfallApp.swift): `SnowfallApp/Sources/SnowfallApp.swift`
- [Menubar Controls](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Views/MenuBarSettings.swift): `SnowfallApp/Sources/Views/MenuBarSettings.swift`
- [Preferences](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/Settings.swift): `SnowfallApp/Sources/Common/Settings.swift`

### Desktop Overlay

- [Overlay Controller](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Views/MetalSnowViewController.swift): `SnowfallApp/Sources/Views/MetalSnowViewController.swift`
- [Render Policy](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowRenderPolicy.swift): `SnowfallApp/Sources/Common/SnowRenderPolicy.swift`

### Snow Simulation

- [Particle Simulation](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowSimulation.swift): `SnowfallApp/Sources/Common/SnowSimulation.swift`
- [Particle Data](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/Snowflake.swift): `SnowfallApp/Sources/Common/Snowflake.swift`
- [Window Detection](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/WindowInfo.swift): `SnowfallApp/Sources/Common/WindowInfo.swift`

### Metal Rendering

- [Frame Renderer](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowRenderer.swift): `SnowfallApp/Sources/Common/SnowRenderer.swift`
- [Metal Shaders](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowShader.metal): `SnowfallApp/Sources/Common/SnowShader.metal`
- [Performance Trace](https://github.com/barredewe/snowfall/blob/main/SnowfallApp/Sources/Common/SnowPerformanceTrace.swift): `SnowfallApp/Sources/Common/SnowPerformanceTrace.swift`

### Other components

- **User**
- **macOS Window APIs**

## Connections

- User → Menubar Controls: adjusts settings (evidence: `README.md`)
- App Lifecycle → Menubar Controls: presents menu (evidence: `SnowfallApp/Sources/SnowfallApp.swift`)
- Menubar Controls → Preferences: updates and saves (evidence: `SnowfallApp/Sources/Views/MenuBarSettings.swift`)
- App Lifecycle → Overlay Controller: creates per screen (evidence: `SnowfallApp/Sources/SnowfallApp.swift`)
- Overlay Controller → Frame Renderer: delegates frames (evidence: `SnowfallApp/Sources/Views/MetalSnowViewController.swift`)
- Overlay Controller → Render Policy: sets display policy (evidence: `SnowfallApp/Sources/Views/MetalSnowViewController.swift`)
- Frame Renderer → Preferences: reads preferences (evidence: `SnowfallApp/Sources/Common/SnowRenderer.swift`)
- Frame Renderer → Particle Simulation: updates particles (evidence: `SnowfallApp/Sources/Common/SnowRenderer.swift`)
- Particle Simulation → Particle Data: initializes particles (evidence: `SnowfallApp/Sources/Common/SnowSimulation.swift`)
- Frame Renderer → Window Detection: queries window bounds (evidence: `SnowfallApp/Sources/Common/SnowRenderer.swift`)
- Window Detection → macOS Window APIs: queries window list (evidence: `SnowfallApp/Sources/Common/WindowInfo.swift`)
- Frame Renderer → Metal Shaders: uses Metal kernels (evidence: `README.md`)
- Frame Renderer → Performance Trace: records GPU frames (evidence: `SnowfallApp/Sources/Common/SnowRenderer.swift`)