# 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`

## Subscriptions & access tiers

Why the app is fully functional with no account or subscription, and what the paid tier actually
gates: the access model (free local-only / subscribed / lapsed-grace), and the decided-but-unbuilt
billing design — auto-renewable IAP via RevenueCat, the Clerk identity as sync owner, schedule-driven
RevenueCat REST entitlement checks anchored at expiry, and a read-only grace period that never blocks
local writes or wipes local data.

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

## End-to-end encryption business case

Legal-risk, trust, marketing, and revenue analysis for making synchronized task content unreadable
to Glide and Convex, including the recovery UX and product tradeoffs.

- Path: `docs/engineering/e2ee-business-case.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`

## EAS Update (over-the-air JS)

How to ship JS-only changes to installed builds without an App Store round-trip: the
build↔channel↔branch↔runtime-version model, the fingerprint constraint (it hashes config and
`.gitignore` but not app JS, so publish from a clean tree or the update silently won't match),
what's OTA-able vs needs a rebuild, and how a device receives an update.

- Path: `docs/engineering/eas-update.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`
