ImageApi/CONTEXT.md

ImageApi

A photo/video memory system: it ingests media from one or more libraries, derives metadata (hashes, dates, faces, insights) that follows the bytes rather than the path, and serves it to two consumers (the Apollo web UI and the FileViewer mobile app) plus a message store (SMS-API).

Language

Dates & time

True instant: The actual moment a photo or video was captured, as Unix seconds. The one clock the whole system matches against — SMS messages, location track points, and photo dates are all true instants, so they compare directly with no conversion. Avoid: epoch, real UTC, wall time

Wall clock: The local time the capturing device showed (e.g. "14:30 on the beach"), independent of where the owner is. A wall clock is not an instant until paired with a zone; it is what the UI's metadata line and insight prompts show so memories read the way the camera remembered them. Avoid: local time, naive date, camera time, date_taken

Camera offset: The zone offset that converts a photo's wall clock into its true instant, resolved per photo at ingest from the most specific evidence available (an explicit EXIF offset tag, then GPS position, then the server's zone as a flagged assumption). Recorded on the row so the conversion is auditable. Avoid: timezone, tz, server offset

Display zone: The IANA zone name of the owner, used for day-level grouping (memories buckets, timelines, daily summaries) and for rendering wall clocks when a photo carries no camera offset. Stored as a zone name, never a fixed minute offset, so DST changes stay correct. Avoid: timezone_offset, tz_offset_minutes, client offset

Date source: Which step of the ingest waterfall filled a photo's date — EXIF tag, external metadata tool, filename, filesystem time, or a manual edit. Recorded per row so weak entries can be re-resolved when a better tool arrives and so any row's date can be explained. Avoid: provenance, origin

Filename date class: Filenames whose name itself carries the capture date (screenshots, timestamp-named exports). For this class the filename is the original date of record and outranks EXIF, even though EXIF wins everywhere else. Each pattern in the class carries its own convention: some names encode a wall clock, others encode a true instant. Avoid: regex dates, name parsing

Manual date: A date the operator sets by hand, expressed as a wall clock in the display zone at edit time and stored as the resulting true instant. The prior value is kept as the original date. Avoid: corrected date, user date

Re-anchoring (legacy): The pre-instant habit of storing wall clocks as if they were UTC and having every consumer shift them back by a zone. Survives only in the frozen legacy column and in the consumer code that migrates off it; new code never re-anchors. Avoid: tz fix, offset correction, naive handling

Derived day data: Insights and pre-computed artifacts grouped by calendar day (daily message summaries, reel pre-generation). Because it is keyed on the day, re-dating a photo across a day boundary invalidates the derived data for that day, which regenerates on its normal schedule. Avoid: cache, nightly output

Configuration

Owner default: A per-request default the owner sets for the whole deployment — the model, backend, persona, reel span, or segment cap a client gets when it omits the field. Stored in the single user_ai_prefs row, hot-tunable without a redeploy, and global: every client that omits the field gets it, on every device. Never holds secrets. Avoid: user prefs, user settings, preferences (ambiguous with device-local client state)

Deployment config: Values the server needs before it can start serving — bind address, database path, media roots, the URLs used to build clients — plus every secret. Lives in .env, except LLM settings, which live in llm.toml (ADR-0003); secrets stay in .env only. Changing it is a restart, by design. Avoid: environment config, system config

Hard default: The config/code fallback (.env, llm.toml or a code constant) a request lands on when neither an explicit param nor a stored owner default supplies the field (e.g. backend local, persona default, reel span day). It is the floor under the owner-default layer: config changes keep working whenever a default column is NULL. Avoid: fallback value, env default