Data model

Everything Tempolight remembers lives in one JSON file, tempolight.json in the data folder (--data, else $TEMPOLIGHT_DATA, else ~/.tempolight). store.js loads it merged over the defaults from defaults.js (merge(DEFAULTS(), saved): objects merge key by key, arrays and values replace), so a file from an older version gets the new keys. A file that can't be parsed is renamed to tempolight.json.broken-<ms> and Tempolight starts fresh.

Writes are debounced (store.save() writes 250 ms after the first change) and atomic (write tempolight.json.tmp, then rename), so a power cut can't corrupt the file. store.flush() writes now (on shutdown); store.reset() writes the defaults. The online demo keeps the same object in localStorage under tempolight.demo.v1 (apps/web/demo.js).

Code reads and writes store.data directly and calls changed(what) in the core (save, plus a {type: "changed", what} broadcast). Modules that own a section fill in its defaults the first time they see it (home, integrations, settings.spotify, settings.homekit, settings.nowPlaying), so a backup from an older version or a hand-edited file works too.

Top-level keys

The demo adds __demoRoom: true once it has laid out its pretend controllers.

settings

Changed with PATCH /api/settings (admin) unless noted; out-of-range numbers are clamped, unknown values are 400 errors.

GET /api/state returns settings with mqtt.password blanked and mqtt.hasPassword added.

show

A scene's show has the same keys (all optional): applying it is Object.assign(show, scene.show).

devices

Common: id (d + 8 hex), name (≤ 60), host (IP or ip:port), ddpPort (the port for its protocol), leds, enabled, optional kind, maxAmps (0-500), mAperLed (5-200, default 60) and lightLatencyMs (0-500, the light's own delay for light timing, set by hand; left out: estimated). By kind (see device kinds):

Nanoleaf tokens and Hue user names and client keys are removed from every API answer (safeDev in core.js).

room

{name, shapes: [Shape], zones: [Zone]}.

• Shape: {type, name, dev (device id), count (1-8192), from (first LED on the controller, or null: after the previous shape), rot, start, rev, zone (zone id or null)} plus geometry: pts: [[x, y], ...] for line, pole, free, points; cx, cy, size (and w, h for rect) for circle, rect, hex, tri; cols, rows (1-256), w, h, cx, cy for matrix (count = cols x rows). Positions are on the 16 x 9 wall view, y = 0 at the top.
• Zone: {id, name, mode: "follow"|"effect"|"ambient"|"off", effect, brightness 0-1}, at most 32 (PUT /api/zones).

scenes, schedules, requests

• Scene: {id, name (≤ 60), show: {...}, brightness}. POST /api/scenes {name} saves the current show.
• Schedule: {id (t + 8 hex), name, time ("18:30" | "sunset" | "sunrise-15"), days: [0-6, Sunday = 0], action: {type: "scene", scene} | {type: "on"} | {type: "off"} | {type: "brightness", value}, enabled}. GET /api/schedules adds next (ISO time).
• Request: {id, title (≤ 120), by (≤ 40), votes, at (ms), done}.

home

{ wake: { enabled: false, source: "times", days: ["", "07:00", "07:00", "07:00", "07:00", "07:00", ""], // Sunday first
          duration: 30, target: "all", endColor: "#ffd2a1", endBrightness: 1, holdMin: 30, snoozeMin: 9, key: "<link key>" },
  sleep: { minutes: 30 },
  plan: { enabled: false, fade: 90, rows: [{name, from, to, look: "white"|"night"|<effect id>, palette, kelvin, brightness}] },
  state: { wake: null, next: null, sleep: null, done: [] } }   // the sunrise running, the next one asked for, the sleep timer, alarms handled

wake.key (the link key for phone automations) is made on first use and only returned to unlocked callers. Changed with PUT /api/home; see wake-up.md.

integrations

Kept outside settings so GET /api/state never shows them; every route that reads or changes them is admin-only, and GET /api/integrations returns hasPassword-style flags instead of secrets.

{ obs: { enabled, url: "ws://127.0.0.1:4455", password, sceneMap: [{obs, scene}], onStreamStart, onStreamStop, onRecordStart,
         tally: { enabled: true, when: "recording", target: "all", color: "#ff0000" } },
  games: { cs2: { enabled, token, intensity: 0.8, mode: "blend", healthTarget, effectsTarget, kills, flashbang, bomb, rounds },
           dota2: { enabled, token, intensity, mode, healthTarget, manaTarget, ambientTarget, effectsTarget, kills, roshan, daynight } },
  twitch: { chat: { enabled, channel, prefix: "!", who: "everyone", cooldownSec: 10, userCooldownSec: 30, commands: {...}, scenes, effects, strobeSec, colorSec },
            clientId, eventsOn: true, target: "all", auth: null | { access, refresh, expiresAt, login, userId, scopes },
            events: { follow, subscribe, resub, gift, raid, cheer } },
  discord: { webhook: "", nowPlaying: true, scenes: true, games: false, twitch: false, username: "Tempolight" } }

Files next to tempolight.json

Secrets and identities that must never reach a browser or a backup are kept in their own files in the data folder, written atomically with mode 0600:

What is and isn't in a backup is listed in security.