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