# sharpbracket/redshift architecture

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

- Interactive diagram: https://gitdiagram.com/sharpbracket/redshift
- Repository: https://github.com/sharpbracket/redshift

## Overview

1. This repository is a cross-platform color-temperature adjustment tool. The core product is the `redshift` command-line program, with an optional `redshift-gtk` graphical wrapper that provides a tray/status icon.

2. The architecture is centered in `src/` and is split into a small orchestration layer plus platform-specific adapters. The main executable (`src/redshift.c`) ties together option parsing, configuration, location lookup, solar/time calculations, and gamma-ramp updates.

3. Configuration and startup flow go through `options.c` and `config-ini.c`. These read CLI flags and `redshift.conf`, producing the runtime parameters that control location, transition behavior, brightness, and backend selection.

4. Location is abstracted behind multiple providers. The repo includes manual coordinates, GeoClue2 on Linux, and CoreLocation on macOS. This is the input side of the scheduling pipeline: once coordinates are known, the app computes local sunrise/sunset behavior.

5. Time-of-day logic lives in `solar.c` and `systemtime.c`. These modules convert location and current time into the target color temperature for the current moment, so the effect can transition smoothly between daytime and nighttime values.

6. The display-adjustment boundary is implemented by backend-specific gamma modules: `gamma-randr.c`, `gamma-vidmode.c`, `gamma-drm.c`, `gamma-quartz.c`, `gamma-w32gdi.c`, and `gamma-dummy.c`. This is the most important abstraction in the project: the rest of the program computes “what color temperature should we apply?”, and the backend layer answers “how do we set it on this platform?”

7. `colorramp.c` is the shared transformation layer used by the backends. It builds and applies the actual gamma ramps/curves that produce the redness effect described in the README, including the “brightness” effect that is implemented as gamma manipulation rather than backlight control.

8. Runtime control and process coordination are handled by utility modules such as `signals.c`, `hooks.c`, and `pipeutils.c`. These support clean shutdown, signal handling, and any subprocess/pipe interaction needed by the wrapper or platform integrations.

9. `src/redshift-gtk/` is a separate Python frontend. It contains a controller and status-icon implementation that manage the user-facing tray app, likely by launching and supervising the main Redshift process rather than reimplementing the display logic.

10. The project is explicitly packaged for multiple operating systems and desktop environments. The tree includes systemd user services, desktop entries, AppArmor policy, macOS launchd support, Windows resource files, and a sample config/man page, indicating that deployment integration is a first-class part of the architecture.

11. Build and release infrastructure is autotools-based (`configure.ac`, `Makefile.am`, `bootstrap`) with translation support under `po/`. That means the source tree is organized for portable native builds, and UI strings are localized across many languages.

12. The key external dependencies and service boundaries are platform services, not cloud APIs: X11/Wayland-adjacent gamma facilities, GeoClue2 on Linux, CoreLocation on macOS, GTK/Python for the tray UI, and systemd/launchd/Windows service-style packaging around the core binary.

13. For an architecture diagram, the main boxes are: user configuration and UI on the left; orchestration/scheduling in the center; location and time inputs below; and platform-specific gamma backends on the right, with packaging/integration artifacts surrounding the runtime on each supported OS.

Main entry points: [`src/redshift.c`](https://github.com/sharpbracket/redshift/blob/master/src/redshift.c) (redshift), [`src/redshift-gtk/controller.py`](https://github.com/sharpbracket/redshift/blob/master/src/redshift-gtk/controller.py) (redshift-gtk), [`src/config-ini.c`](https://github.com/sharpbracket/redshift/blob/master/src/config-ini.c) (Config INI), [`configure.ac`](https://github.com/sharpbracket/redshift/blob/master/configure.ac) (Autotools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI & Packaging"]
  node_redshift_gtk["redshift-gtk<br/>python wrapper<br/>[controller.py]"]
  node_statusicon["Status Icon<br/>tray ui<br/>[statusicon.py]"]
  node_packaging["Packaging<br/>deploy artifacts"]
end

subgraph group_core["Core Engine"]
  node_redshift_main["redshift<br/>cli program<br/>[redshift.c]"]
  node_options["Options<br/>cli parse<br/>[options.c]"]
  node_config_ini["Config INI<br/>config load<br/>[config-ini.c]"]
  node_solar["Solar<br/>sun calc<br/>[solar.c]"]
  node_systemtime["System Time<br/>clock input<br/>[systemtime.c]"]
  node_colorramp["Color Ramp<br/>gamma transform<br/>[colorramp.c]"]
  node_signals["Signals<br/>lifecycle<br/>[signals.c]"]
  node_hooks["Hooks<br/>integration<br/>[hooks.c]"]
  node_pipeutils["Pipe Utils<br/>process io<br/>[pipeutils.c]"]
end

subgraph group_platform["Platform Backends"]
  node_location_manual["Manual Location<br/>location provider<br/>[location-manual.c]"]
  node_location_geoclue2["GeoClue2<br/>location provider"]
  node_location_corelocation["CoreLocation<br/>location provider"]
  node_gamma_randr["RANDR<br/>gamma backend<br/>[gamma-randr.c]"]
  node_gamma_vidmode["VidMode<br/>gamma backend<br/>[gamma-vidmode.c]"]
  node_gamma_drm["DRM<br/>gamma backend<br/>[gamma-drm.c]"]
  node_gamma_quartz["Quartz<br/>gamma backend<br/>[gamma-quartz.c]"]
  node_gamma_w32gdi["W32 GDI<br/>gamma backend<br/>[gamma-w32gdi.c]"]
  node_gamma_dummy["Dummy<br/>gamma backend<br/>[gamma-dummy.c]"]
end

subgraph group_build["Build & Locales"]
  node_autotools["Autotools<br/>build system<br/>[configure.ac]"]
  node_po["Translations<br/>localization<br/>[POTFILES.in]"]
end

node_redshift_main -->|"parse"| node_options
node_redshift_main -->|"load"| node_config_ini
node_redshift_main -->|"location"| node_location_manual
node_redshift_main -->|"location"| node_location_geoclue2
node_redshift_main -->|"location"| node_location_corelocation
node_redshift_main -->|"schedule"| node_solar
node_redshift_main -->|"clock"| node_systemtime
node_redshift_main -->|"apply"| node_colorramp
node_redshift_main -->|"backend"| node_gamma_randr
node_redshift_main -->|"backend"| node_gamma_vidmode
node_redshift_main -->|"backend"| node_gamma_drm
node_redshift_main -->|"backend"| node_gamma_quartz
node_redshift_main -->|"backend"| node_gamma_w32gdi
node_redshift_main -->|"fallback"| node_gamma_dummy
node_redshift_main -->|"lifecycle"| node_signals
node_redshift_main -->|"events"| node_hooks
node_redshift_gtk -->|"ui"| node_statusicon
node_redshift_gtk -->|"supervise"| node_pipeutils
node_redshift_gtk -.->|"launch"| node_redshift_main
node_packaging -->|"deploy"| node_redshift_main
node_packaging -->|"deploy"| node_redshift_gtk
node_autotools -->|"build"| node_redshift_main
node_autotools -->|"build"| node_redshift_gtk
node_autotools -->|"localize"| node_po
node_options -->|"merge"| node_config_ini
node_config_ini -->|"select"| node_location_manual
node_config_ini -->|"select"| node_gamma_randr

click node_redshift_main "https://github.com/sharpbracket/redshift/blob/master/src/redshift.c"
click node_options "https://github.com/sharpbracket/redshift/blob/master/src/options.c"
click node_config_ini "https://github.com/sharpbracket/redshift/blob/master/src/config-ini.c"
click node_solar "https://github.com/sharpbracket/redshift/blob/master/src/solar.c"
click node_systemtime "https://github.com/sharpbracket/redshift/blob/master/src/systemtime.c"
click node_colorramp "https://github.com/sharpbracket/redshift/blob/master/src/colorramp.c"
click node_signals "https://github.com/sharpbracket/redshift/blob/master/src/signals.c"
click node_hooks "https://github.com/sharpbracket/redshift/blob/master/src/hooks.c"
click node_pipeutils "https://github.com/sharpbracket/redshift/blob/master/src/pipeutils.c"
click node_location_manual "https://github.com/sharpbracket/redshift/blob/master/src/location-manual.c"
click node_location_geoclue2 "https://github.com/sharpbracket/redshift/blob/master/src/location-geoclue2.c"
click node_location_corelocation "https://github.com/sharpbracket/redshift/blob/master/src/location-corelocation.m"
click node_gamma_randr "https://github.com/sharpbracket/redshift/blob/master/src/gamma-randr.c"
click node_gamma_vidmode "https://github.com/sharpbracket/redshift/blob/master/src/gamma-vidmode.c"
click node_gamma_drm "https://github.com/sharpbracket/redshift/blob/master/src/gamma-drm.c"
click node_gamma_quartz "https://github.com/sharpbracket/redshift/blob/master/src/gamma-quartz.c"
click node_gamma_w32gdi "https://github.com/sharpbracket/redshift/blob/master/src/gamma-w32gdi.c"
click node_gamma_dummy "https://github.com/sharpbracket/redshift/blob/master/src/gamma-dummy.c"
click node_redshift_gtk "https://github.com/sharpbracket/redshift/blob/master/src/redshift-gtk/controller.py"
click node_statusicon "https://github.com/sharpbracket/redshift/blob/master/src/redshift-gtk/statusicon.py"
click node_packaging "https://github.com/sharpbracket/redshift/blob/master/data/systemd/redshift.service.in"
click node_autotools "https://github.com/sharpbracket/redshift/blob/master/configure.ac"
click node_po "https://github.com/sharpbracket/redshift/blob/master/po/POTFILES.in"

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_redshift_gtk,node_statusicon,node_packaging toneBlue
class node_redshift_main,node_options,node_config_ini,node_solar,node_systemtime,node_colorramp,node_signals,node_hooks,node_pipeutils toneAmber
class node_location_manual,node_location_geoclue2,node_location_corelocation,node_gamma_randr,node_gamma_vidmode,node_gamma_drm,node_gamma_quartz,node_gamma_w32gdi,node_gamma_dummy toneMint
class node_autotools,node_po toneRose
```

## Components

### UI & Packaging

User-facing wrapper and deployment artifacts around the core binary.

- [redshift-gtk](https://github.com/sharpbracket/redshift/blob/master/src/redshift-gtk/controller.py): python wrapper · GTK tray/status-icon frontend that supervises the core program. · `src/redshift-gtk/controller.py`
- [Status Icon](https://github.com/sharpbracket/redshift/blob/master/src/redshift-gtk/statusicon.py): tray ui · Tray/status icon presentation and user interaction layer. · `src/redshift-gtk/statusicon.py`
- [Packaging](https://github.com/sharpbracket/redshift/blob/master/data/systemd/redshift.service.in): deploy artifacts · Desktop entries, services, launchd, AppArmor, Windows resources, and sample config. · `data/systemd/redshift.service.in`

### Core Engine

Runtime orchestration, scheduling, and color adjustment pipeline.

- [redshift](https://github.com/sharpbracket/redshift/blob/master/src/redshift.c): cli program · Main executable that orchestrates parsing, location, timing, and output updates. · `src/redshift.c`
- [Options](https://github.com/sharpbracket/redshift/blob/master/src/options.c): cli parse · Reads command-line flags and startup options. · `src/options.c`
- [Config INI](https://github.com/sharpbracket/redshift/blob/master/src/config-ini.c): config load · Parses redshift.conf and produces runtime settings. · `src/config-ini.c`
- [Solar](https://github.com/sharpbracket/redshift/blob/master/src/solar.c): sun calc · Computes sunrise/sunset-based transition timing from coordinates. · `src/solar.c`
- [System Time](https://github.com/sharpbracket/redshift/blob/master/src/systemtime.c): clock input · Provides current time and local time-of-day inputs. · `src/systemtime.c`
- [Color Ramp](https://github.com/sharpbracket/redshift/blob/master/src/colorramp.c): gamma transform · Builds and applies gamma ramps and brightness-related curves. · `src/colorramp.c`
- [Signals](https://github.com/sharpbracket/redshift/blob/master/src/signals.c): lifecycle · Handles shutdown and signal coordination. · `src/signals.c`
- [Hooks](https://github.com/sharpbracket/redshift/blob/master/src/hooks.c): integration · Runs external hooks or coordinated actions around runtime events. · `src/hooks.c`
- [Pipe Utils](https://github.com/sharpbracket/redshift/blob/master/src/pipeutils.c): process io · Utility support for subprocess and pipe interactions. · `src/pipeutils.c`

### Platform Backends

OS-specific location and gamma adapters.

- [Manual Location](https://github.com/sharpbracket/redshift/blob/master/src/location-manual.c): location provider · Uses user-supplied coordinates. · `src/location-manual.c`
- [GeoClue2](https://github.com/sharpbracket/redshift/blob/master/src/location-geoclue2.c): location provider · Linux location backend using GeoClue2. · `src/location-geoclue2.c`
- [CoreLocation](https://github.com/sharpbracket/redshift/blob/master/src/location-corelocation.m): location provider · macOS location backend using CoreLocation. · `src/location-corelocation.m`
- [RANDR](https://github.com/sharpbracket/redshift/blob/master/src/gamma-randr.c): gamma backend · X11 RANDR gamma backend. · `src/gamma-randr.c`
- [VidMode](https://github.com/sharpbracket/redshift/blob/master/src/gamma-vidmode.c): gamma backend · X11 VidMode gamma backend. · `src/gamma-vidmode.c`
- [DRM](https://github.com/sharpbracket/redshift/blob/master/src/gamma-drm.c): gamma backend · Direct rendering gamma backend. · `src/gamma-drm.c`
- [Quartz](https://github.com/sharpbracket/redshift/blob/master/src/gamma-quartz.c): gamma backend · macOS Quartz gamma backend. · `src/gamma-quartz.c`
- [W32 GDI](https://github.com/sharpbracket/redshift/blob/master/src/gamma-w32gdi.c): gamma backend · Windows GDI gamma backend. · `src/gamma-w32gdi.c`
- [Dummy](https://github.com/sharpbracket/redshift/blob/master/src/gamma-dummy.c): gamma backend · No-op backend for unsupported or testing cases. · `src/gamma-dummy.c`

### Build & Locales

Portable build system and translation assets.

- [Autotools](https://github.com/sharpbracket/redshift/blob/master/configure.ac): build system · configure.ac, Makefile.am, and bootstrap-based native build tooling. · `configure.ac`
- [Translations](https://github.com/sharpbracket/redshift/blob/master/po/POTFILES.in): localization · Message catalogs and translation metadata. · `po/POTFILES.in`

## Connections

- redshift → Options: parse · Loads CLI options at startup.
- redshift → Config INI: load · Merges configuration file settings.
- redshift → Manual Location: location · Uses manual coordinates when selected.
- redshift → GeoClue2: location · Queries Linux location service when available.
- redshift → CoreLocation: location · Queries macOS location service when available.
- redshift → Solar: schedule · Computes transition timing from location.
- redshift → System Time: clock · Reads current time for transition state.
- redshift → Color Ramp: apply · Generates and applies the target gamma ramp.
- redshift → RANDR: backend · Uses X11 RANDR output path.
- redshift → VidMode: backend · Uses X11 VidMode output path.
- redshift → DRM: backend · Uses DRM output path.
- redshift → Quartz: backend · Uses macOS gamma path.
- redshift → W32 GDI: backend · Uses Windows gamma path.
- redshift → Dummy: fallback · Uses no-op backend when needed.
- redshift → Signals: lifecycle · Coordinates clean shutdown and signal handling.
- redshift → Hooks: events · Triggers runtime hooks around state changes.
- redshift-gtk → Status Icon: ui · Provides the tray/status icon experience.
- redshift-gtk → Pipe Utils: supervise · Relies on process and pipe helpers to manage the core app.
- redshift-gtk → redshift: launch · Starts and supervises the core Redshift process.
- Packaging → redshift: deploy · Packages the main CLI binary for multiple platforms.
- Packaging → redshift-gtk: deploy · Packages the GTK wrapper and desktop integration.
- Autotools → redshift: build · Builds the core executable.
- Autotools → redshift-gtk: build · Builds the Python/GTK frontend assets.
- Autotools → Translations: localize · Integrates message catalogs into builds.
- Options → Config INI: merge · CLI overrides config-file defaults.
- Config INI → Manual Location: select · Chooses the configured location source.
- Config INI → RANDR: select · Chooses the configured gamma backend.
