# Engineering

Implementation notes for the subsystems whose behaviour isn't obvious from the
code alone — the parts where a wrong assumption costs real debugging time. Read
the relevant note before changing these areas.

## Local-first data layer

How Glide stores its data on-device (MMKV + a Zustand store) so every feature works
with no account, no network, and no Convex link; the repository seam the UI talks to;
the sync-ready shape of a stored task; and how an optional Convex sync attaches later.

- Path: `docs/engineering/local-first.md`

## Convex sync

How the local store syncs to Convex (single-user / dogfood mode today): an offline outbox of
optimistic writes, idempotent upserts keyed by the client UUID, last-write-wins conflict
resolution, the two auth swap points, and why it deliberately avoids a CRDT.

- Path: `docs/engineering/convex-sync.md`

## Schema migrations (zero-downtime)

The widen→migrate→narrow process for breaking Convex schema changes with a lingering mobile
client: the read/write asymmetry, the forward-compat client step, the `@convex-dev/migrations`
component, and a worked example (removing a column).

- Path: `docs/engineering/migrations.md`

## Home-screen widget

The iOS home-screen widget (`expo-widgets`): how its UI is authored and shipped to
a separate WidgetKit runtime, the local board → widget bridge, and the gotchas of
that runtime (serialised body, payload constraints, App Group signing).

- Path: `docs/engineering/home-screen-widget.md`

## Liquid Glass surfaces

The Action view's scroll-driven Liquid Glass header & footer: the layout that lets
content scroll behind them, and the Reanimated opacity-animation workaround that
fades the glass in and out without breaking the effect.

- Path: `docs/engineering/liquid-glass.md`
