ImageApi/docs/adr/0002-owner-defaults-vs-env.md

ADR-0002: Owner defaults live in the DB row; .env keeps deployment config and secrets

Status: accepted (2026-09-27)

Context

All configuration lived in .env: bind address, media paths, Ollama/llama-swap/OpenRouter URLs, model names, LLM_BACKEND, the embedding contract, TTS voices. Two friction points: values the owner actually tunes (which model, which backend, which persona, how long a reel is) needed an edit + redeploy to change, and clients had no server-side fallback — "use the default" was expressed by omitting a field, and the default itself was invisible and untouchable at runtime. The user_ai_prefs single row (id = 1) already existed as a passive mirror of the last client reel request for the nightly pre-gen. #126/#127 gave it an explicit PUT /prefs surface and five owner-default columns (default_model, default_backend, default_persona_id, reel_span, reel_max_segments) — the first batch of non-private configuration moved out of .env and into the database.

Decision

Configuration splits into two homes by one rule — does the server need the value before it can start serving?

• .env (deployment config): everything read at boot to bind, connect, or open — BIND_URL, DATABASE_URL, media paths, OLLAMA_*_URL / LLAMA_SWAP_URL, LLM_BACKEND, the embedding contract — and all secrets (OPENROUTER_API_KEY, SECRET_KEY, SMS_API_TOKEN). Secrets never go in the database: the SQLite file gets backed up, copied, and attached to bug reports.
• user_ai_prefs (owner defaults): per-request defaults resolved at request time — the model/backend/persona a client gets when it omits the field, reel span and segment cap, display zone, TTS voice. Hot-tunable via PUT /prefs, effective on the next request, no redeploy. This row is the designated home for future non-private, per-request configuration that outgrows .env. The table is a single row per deployment, not a per-user profile — user_ai_prefs is a historical name; the canonical term is owner defaults (single-user tool: owner = admin).

Resolution order at every consumer: explicit request param → stored owner default → hard default (the env/code fallback). An explicit request always wins, so any client can override the owner's default per request. The env value stays the floor under the DB: a NULL default_model means "whatever the Ollama/llama-swap primary is", so env changes keep working.

Privacy posture is safe-by-default. default_backend is the one owner default with network-egress consequences: hybrid routes insight generation and chat to OpenRouter. With no row or a NULL column, the hard default is local — data stays on the LAN. Leaving the network requires an explicit owner action (storing hybrid), and any client can still pin itself by sending backend explicitly. Owner defaults therefore split into two sensitivity classes: harmless tuning (span, segments, display zone, voice, model, persona) and privacy/security (default_backend), which any admin UI must surface with a warning, not a quiet dropdown.

Considered options

• Everything in .env (status quo): safe, but tuning a model default means edit + redeploy, and clients have no server-side default to fall back to — a picker's "server default" is just the env value, invisible and unchangeable at runtime. Rejected for per-request defaults.
• Everything in the DB: boot-time values (bind address, DB path, the URLs used to build the HTTP clients) become chicken-and-egg, and secrets sit next to tuning values in a file that gets copied around. Rejected.
• A separate system_config table: cleaner name, but a second single-row table would be a synonym with extra migrations; the row and the PUT /prefs surface already exist. Rejected — the row keeps its name, its term becomes owner defaults.

Non-obvious rules worth remembering

• Owner defaults are global to the deployment. Every client that omits a field gets the stored value, on every device. Storing default_backend=hybrid changes the mobile app's behavior even for users who never touch the setting; a client that must stay local should send backend explicitly (tracked for FileViewer-React #33).
• A stored value that is no longer consumable fails at write time, not request time — PUT /prefs validates default_backend against the canonical BackendKind::parse and reel_span against the span enum before writing, so a bad default cannot 500 every request later.
• The passive reel mirror (capture_prefs) may only write the fields it owns (voice, library, display zone, effective span/segments); it carries the AI owner-defaults through unchanged, because the upsert overwrites every column.
• NULL means "use the hard default", not "unset the env" — the DB layer sits above env, never instead of it.