familysync/.planning/research/PITFALLS.md

Pitfalls Research — v1.2 Multi-Provider, Theming & Zero-Setup

Domain: Adding Google Calendar OAuth2, provider abstraction, multiple reminders, dark mode, auto-migrate-on-boot, self-service OAuth onboarding, and dependency updates to a shipped Node 22 + Hono 4 + Drizzle/MariaDB 11 + tsdav/ical.js + web-push stack on Unraid/Docker behind Authelia OIDC + Pangolin/Newt. Researched: 2026-06-19 Confidence: HIGH — pitfalls derived from direct source inspection of the shipped v1.1 codebase, v1.0/v1.1 retrospectives, known burned-in lessons from the migration and CI history, and deep familiarity with Google Calendar API, OAuth2, Drizzle/MariaDB migration semantics, and PWA theming constraints. Sources cross-checked against PROJECT.md, RETROSPECTIVE.md, MILESTONES.md, and the VALARM/outbox source in apps/api/src/broker/.

---

Known Constraints (Inherited — Do Not Re-Litigate)

These are burned-in from v1.0/v1.1. Every pitfall below assumes these hold:

• No node-cron. setInterval only — node-cron 4.2.1 silently skips all ticks in long-lived Node processes.
• drizzle-kit generate+migrate, never push. push emits a false destructive diff (TRUNCATE/DROP) on populated MariaDB 11 using the mysql dialect — the introspection bug fires on any existing-data DB. This is the root cause behind D-MIGRATION-10-01 and the quick task cr8.
• Journal-hash matching is mandatory. The __drizzle_migrations table tracks applied migrations by tag (from _journal.json). If a migration file is renamed, regenerated, or its journal entry is modified after it has been applied to any environment, drizzle-kit migrate treats it as unapplied and will attempt to re-run DDL that already ran — producing Duplicate column errors.
• MariaDB CI readiness uses healthcheck.sh --connect, not mysqladmin ping. mysqladmin ping was removed in MariaDB 11.
• ESLint is pinned at 9.39.4. ESLint 10 breaks eslint-plugin-react and eslint-plugin-react-hooks. The root package.json pin must not be bumped past 9.x until all React plugins declare ESLint 10 peerDep support.
• setInterval outbox drain, not Redis. Single-process; in-process EventEmitter (outboxTrigger.ts) for the drain signal. drainRequested flag pattern prevents double-drain. Optimistic-202, create-before-delete, and uid:dtstartMs dedup are load-bearing.
• All CalDAV VALARM triggers must be built via ICAL.Duration.fromSeconds(-N*60), not bare strings. Bare strings produce VALUE=TEXT which is rejected by Fastmail and Apple Calendar.
• REGISTRY_PAT secret name (not GITEA_PAT — the GITEA_ prefix is silently dropped by Gitea Actions). docker login --password-stdin, never -p $TOKEN on the command line.

---

Critical Pitfalls

Pitfall 1: Google Refresh Tokens in "Testing" Publishing Status Expire After 7 Days

What goes wrong: Google OAuth2 refresh tokens issued to an app in "Testing" publishing status (as opposed to "Production") expire after 7 days regardless of the token TTL in the credentials. After 7 days, the stored refresh token returns invalid_grant and all Google Calendar operations fail for that member. The user sees calendar data vanish or receives 401 errors, and the fix requires them to re-authorize — a confusing, non-obvious failure for a non-technical user.

Additionally, Google refresh tokens for apps in "Testing" status can only be granted to users explicitly listed as "test users" in the OAuth consent screen. If the operator adds a second member's Google account but forgets to add them as a test user, the authorization flow returns access_denied at the consent step, not a useful error message.

Why it happens: Developers set up the OAuth app in "Testing" status because "Production" requires Google verification (which requires a privacy policy, domain verification, and Google review). Testing status is the path of least resistance during development and stays in place longer than intended.

How to avoid: For a self-hosted household app serving 2 users, request "Production" publishing status immediately — it does not require Google's full verification unless the app accesses sensitive scopes. For calendar read/write, https://www.googleapis.com/auth/calendar is a "restricted" scope (not "sensitive"), which DOES require verification. Use https://www.googleapis.com/auth/calendar.readonly + https://www.googleapis.com/auth/calendar.events instead — these are the non-restricted scopes sufficient for event read/write (no attendee PII access). With these scopes, production status is grantable without full Google review.

If testing status must remain during development, encode a token_expiry_check that validates the refresh token age and prompts re-auth before it expires rather than failing silently. Store the token grant timestamp alongside the encrypted refresh token in member_credentials.

Add the operator's and wife's Google accounts as test users in the OAuth consent screen during development.

Warning signs:

• Calendar data disappears exactly 7 days after a member connected their Google account.
• invalid_grant error in API logs when refreshing Google tokens.
• Second member's authorization flow returns access_denied.

Phase to address: Google Calendar provider phase (first Google OAuth plan). Document the testing-vs-production publishing status distinction in the onboarding UI and in docs/deployment.md before implementing the OAuth flow.

---

Pitfall 2: Google Calendar Recurrence Model Does Not Map Cleanly to iCalendar RRULE

What goes wrong: The Google Calendar API represents recurring events as a "master event" with a recurrence field (an array of raw iCalendar strings like ["RRULE:FREQ=WEEKLY;BYDAY=MO"]) plus separate "instance" resources for occurrences that have been individually modified (moved, canceled). The FamilySync codebase assumes the iCalendar model where: (a) a single VEVENT with RRULE expands to all occurrences via ICAL.RecurExpansion, and (b) exceptions are represented as VEVENT objects with RECURRENCE-ID.

When pulling Google recurring events, the Google API returns individual instance resources by default in events.list — unless you pass singleEvents: false. If singleEvents: true (the default), you get individual expanded occurrences, not the master event. You cannot reconstruct the RRULE from the instances. If singleEvents: false, you get the master event (with RRULE) but also need to separately fetch modified instances to know which occurrences have been moved or canceled. There is no single API call that returns "master event + delta patches in RECURRENCE-ID form" like CalDAV does.

Deleted/canceled individual occurrences in Google Calendar have status: "cancelled" — they are not omitted from the response. If your code filters on status === "confirmed" you silently drop the cancellation records and re-expand the occurrence the next time the RRULE expands, causing ghost events.

Why it happens: The CalDAV model and the Google Calendar API model for recurrence are fundamentally different. CalDAV treats recurrence as an iCalendar artifact (RRULE on the master VEVENT, RECURRENCE-ID VEVENTs for exceptions). The Google API wraps iCalendar but exposes a different resource model. Developers assume the broker abstraction can produce identical event shapes from both providers, but the Google recurrence model requires a different fetch strategy.

How to avoid: Fetch Google events with singleEvents: false to get master events with RRULE. For any recurring master event, issue a second call to fetch its instances (events.instances()) to get modified/canceled occurrences. Map status: "cancelled" instance resources to EXDATE entries on the master event's RRULE. Use ICAL.RecurExpansion on the reconstructed VCALENDAR for display, same as the Fastmail path.

The provider abstraction interface should return normalized VEVENT strings (raw iCalendar text), not provider-specific objects. The Google adapter's job is to produce a VCALENDAR string (including reconstructed RRULE + EXDATE) that the existing expand.ts / sync.ts layer can handle without modification.

Expose a fetchRecurringMasterWithExceptions(uid) method in the Google adapter that issues both API calls and returns a unified VCALENDAR string. Do not attempt to normalize at the events.list level.

Warning signs:

• Recurring events show individual occurrences as separate events in the calendar instead of a recurring series.
• Canceled occurrences still appear in the calendar after being deleted in Google Calendar.
• singleEvents: true is used in the Google API client — this is wrong for the FamilySync data model.

Phase to address: Google Calendar provider phase (recurrence handling plan). Write a unit test that takes a Google events.list response (with a recurring master + a modified instance + a canceled instance) and asserts the reconstructed VCALENDAR string passes ical.js parsing and ICAL.RecurExpansion without error.

---

Pitfall 3: Google syncToken Invalidation Triggers Silent Full Re-Sync That Overwrites Local Writes

What goes wrong: The Google Calendar API supports incremental sync via syncToken: call events.list with the token from the previous response to receive only changes since the last sync. When the sync token expires (after ~7 days of inactivity, or after any large state change like timezone change or Google-side recalculation), the API returns HTTP 410 Gone. The correct response is to perform a full re-sync (no syncToken, save the new token). If the code does not handle 410 — or handles it by retrying with the old token — all incremental sync calls return 410 forever, silently halting all calendar updates.

A second issue: during a full re-sync, the code fetches all events and upserts into calendar_events. If a member created an event in FamilySync that is in the outbox (not yet written to Google), and the full re-sync runs before the outbox drains, the upsert overwrites the local optimistic row with the stale Google state (the event is not yet on Google's side), effectively reverting the user's creation. The event disappears from the UI until the next outbox drain re-creates it on Google and the next poller sync pulls it back.

Why it happens: syncToken expiration is handled in Google's CalDAV-via-ICAL model too (ctag changes trigger full re-sync), but the FamilySync ctag-based poller handles this correctly. The Google syncToken path is a different code branch that does not inherit the ctag handling. Full re-sync without outbox-awareness is a standard oversight.

How to avoid: Wrap every events.list call that uses a syncToken in a try/catch for 410. On 410: drop the sync token, mark the provider's sync state as stale, and enqueue a full re-sync on the next poller tick (not in-band, to avoid blocking the current poller iteration).

Before upsetting rows from a full re-sync, check the calendar_outbox table for any pending rows for the same user/calendar. If any pending writes exist for the same event UID, skip overwriting that row's raw_vevent from Google — the outbox write is the authoritative source of truth until it drains. Alternatively: drain the outbox before any full re-sync. The outbox drain is already ~1–2s; blocking the re-sync on it is acceptable.

Warning signs:

• API logs show HTTP 410 from Google Calendar and the app stops updating events for that member.
• Events created via FamilySync disappear briefly then reappear.
• syncToken is stored per-provider in member_credentials or a separate provider_sync_state table but there is no 410 error handler branch.

Phase to address: Google Calendar provider phase (sync/poller plan). 410 handling must be in the acceptance criteria before the Google poller ships.

---

Pitfall 4: Google All-Day Events Use DATE, Timed Events Use RFC 3339 — Timezone Handling Differs From CalDAV

What goes wrong: Google Calendar returns timed events with start.dateTime (RFC 3339 string with timezone offset, e.g., 2026-07-01T10:00:00-04:00) and all-day events with start.date (ISO 8601 date string, e.g., 2026-07-01). The FamilySync sync layer (sync.ts) currently parses raw iCalendar DTSTART;TZID=America/Toronto:20260701T100000 strings via ical.js and stores the UTC instant in dtstart_utc.

When the Google adapter converts start.dateTime to iCalendar, it must produce DTSTART:20260701T140000Z (UTC). If it instead produces DTSTART;TZID=America/Toronto:20260701T100000, ical.js parses it correctly, but only if the corresponding VTIMEZONE component is also present in the VCALENDAR. Google does not return VTIMEZONE components — their API uses offset strings. A missing VTIMEZONE for a TZID reference causes ical.js to default to UTC, silently shifting the event time.

All-day event reminder handling has a separate pitfall: the computeAlertInstantUtc function in vevent.ts uses getHouseholdTimezone(db) (the stored IANA timezone) to compute "9 AM local on alert day." For Google all-day events, the Google API returns reminders.overrides (a list of {method, minutes} objects) or reminders.useDefault (boolean). If useDefault: true, the reminder fires at the user's Google Calendar default reminder time (from their Google account settings) — which the server cannot know. Mapping useDefault: true to a reminderLeadMinutes value in FamilySync is undefined.

Why it happens: CalDAV stores full iCalendar with VTIMEZONE. The Google API abstracts timezone into RFC 3339 offsets. The two representations look similar but require different handling in ical.js. Developers test with US/Eastern events and miss that ical.js silently falls back to UTC for an unknown TZID.

How to avoid: In the Google adapter, always normalize start.dateTime to UTC before building the iCalendar string. Use new Date(googleEvent.start.dateTime).toISOString() to get the UTC instant, then build DTSTART:20260701T140000Z. Never emit a TZID reference without a corresponding VTIMEZONE block.

For all-day events: map start.date directly to DTSTART;VALUE=DATE:20260701, same as the CalDAV path.

For Google reminders.useDefault: true: treat it as "no reminder" at the FamilySync layer. Store reminderLeadMinutes: null. Document this in the UI: "Google default reminders from your Google account settings are not shown in FamilySync; set a reminder here to receive FamilySync push notifications." This avoids fetching and storing per-member Google account preferences.

For Google reminders.overrides: map the first email-method reminder to reminderLeadMinutes (FamilySync uses push, not email). Ignore popup method overrides unless there is a clear 1:1 mapping.

Warning signs:

• Timed events from Google appear at the wrong time in FamilySync (off by the timezone offset).
• ical.js warnings about unknown TZID in the server logs.
• All-day events with useDefault: true trigger unexpected push notifications.

Phase to address: Google Calendar provider phase (event normalization plan). Write unit tests for the UTC normalization: assert that a start.dateTime with -04:00 offset produces DTSTART:...Z with the correct UTC instant, and that a missing VTIMEZONE is never emitted.

---

Pitfall 5: Provider Abstraction Refactor Regresses the Live Fastmail Path

What goes wrong: Extracting a CalendarProvider interface from the existing CalDAV code requires moving the tsdav client, sync logic, poller, outbox worker, and reminder scheduler from Fastmail-specific code into an abstraction layer. The risk is that the refactor introduces a regression on the Fastmail path: a subtle behavioral change in the outbox worker (e.g., enqueue ordering, isDraining guard, or the drainRequested flag) can cause:

• Duplicate CalDAV PUTs (double-drain race reintroduced).
• Create-before-delete ordering broken for move operations.
• The ctag-based poller not calling the new interface method in the correct order (poll → sync → schedule).
• The uid:dtstartMs dedup key in the reminder scheduler falling back to uid alone if the schema type changes during the refactor.

A specific risk: the outbox worker currently reads provider_type from member_credentials but the only implemented value is 'caldav'. During refactor, if the worker is changed to dispatch to a provider-specific write() method, and the CalDAV write path is accidentally placed behind a provider_type === 'google' branch instead of provider_type === 'caldav', all existing Fastmail write-back silently stops with no error (the wrong branch simply does nothing).

Why it happens: Refactors that extract interfaces from working code are high-regression-risk because the tests were written against the concrete implementation. The test suite may pass because it stubs the CalDAV calls but not the new interface dispatch, so the dispatch logic change is never exercised by tests.

How to avoid: Refactor behind a feature flag or in a branch that keeps the Fastmail path fully operational throughout. Do not merge the provider abstraction until all existing CalDAV integration tests (outbox, poller, ctag, reminder scheduler) pass unchanged against the new interface.

Write a golden-path integration test for the Fastmail provider specifically: enqueue a write → assert it reaches the CalDAV mock → assert the outbox row is marked done. This test must pass before and after the refactor with no modification.

Keep the provider_type === 'caldav' dispatch path as the default/fallback. The Google path (provider_type === 'google') is additive; it must not be required for the existing Fastmail path to work.

The abstraction interface should be defined from the consumer's perspective (what outboxWorker.ts and poller.ts need), not from the CalDAV implementation's perspective. Avoid leaking tsdav types (DAVCalendar, DAVObject) into the interface — callers should see normalized event objects.

Warning signs:

• Any existing CalDAV integration test is modified during the refactor (should be zero changes to existing tests).
• The outbox worker has a branch that exits without calling any write method for provider_type === 'caldav'.
• The provider_type column contains 'caldav' for all existing rows but the refactored dispatch uses string equality without a default case.

Phase to address: Provider abstraction phase (first). Must ship before any Google Calendar code is written. The acceptance gate is: all v1.1-passing integration tests still pass, unchanged, with the abstraction layer in place.

---

Pitfall 6: Multiple VALARMs — Duplicate Fire and Preserve-vs-Replace Ambiguity

What goes wrong: v1.2 adds multiple reminders per event (multiple VALARMs on a single VEVENT). The v1.1 reminder scheduler deduplicates on uid:dtstartMs — one dedup entry per event. With multiple VALARMs, a single event now needs multiple push notifications at different lead times. If the dedup key is still uid:dtstartMs, only the first alarm fires; subsequent alarms for the same event at different leads are treated as "already sent" by the dedup map.

A second issue: the scheduler currently runs a SQL query for events where reminderLeadMinutes IS NOT NULL. With multiple reminders stored as multiple VALARM objects in rawVevent (and potentially as a JSON array or repeated column), the SQL query must change to a per-VALARM lead-time scan. If the query fetches one row per event and picks the first VALARM lead only, subsequent alarms are silently skipped.

A third issue: the VALARM preserve-on-edit path (D-08 / CAL-14, shipped in Phase 11) extracts all existing VALARMs from rawVevent and re-attaches them. With multiple VALARMs, if the user adds a new reminder in the FamilySync UI (which produces one VALARM from the picker), the preserve path must decide: replace all existing VALARMs with the single new one, or append? The current single-reminder model implicitly "replace all." Multiple-reminder UI changes this intent.

A fourth issue: Google Calendar caps reminders at 5 per event (reminders.overrides max 5). If the user creates 6 reminders in FamilySync and the event is in a Google Calendar, the write-back to the Google Calendar API returns a 400 error. The error must be caught and surfaced to the user before the write, not as a silent failure.

Why it happens: The v1.1 architecture was designed for exactly one VALARM per event (the picker is single-selection). Multiple VALARM support requires rethinking the dedup key, the SQL query, the preserve logic, and the write-back validation.

How to avoid: Change the scheduler dedup key to uid:dtstartMs:leadMinutes (three-part key). Each VALARM on an event gets its own dedup entry, and each fires independently.

Store multiple reminder leads in a normalized form. Two options: (a) a event_reminders junction table (event_id, lead_minutes), or (b) a JSON array column reminder_lead_minutes_json on calendar_events. Option (a) is cleaner for SQL querying; option (b) avoids a second migration and join. For a two-user household, option (b) is acceptable. The SQL scheduler query must unnest or join to iterate per-lead.

For the preserve-on-edit path: the UI must distinguish "user changed reminders" from "user changed something else (title, time, location)." If reminders were not touched, preserve all existing VALARMs. If the user opened the reminder editor and submitted, replace all VALARMs with the new set. This is a frontend concern: include a remindersChanged: boolean flag in the outbox payload alongside the new reminderLeads: number[] array.

For Google Calendar cap validation: add a Zod validator on the outbox payload schema that rejects more than 5 reminder leads when the provider is Google. Surface the error in the form before submit.

Warning signs:

• Second and third reminders on an event never fire.
• The scheduler sends duplicates for the first alarm on every tick (dedup not working after key change).
• Events with 6+ reminders silently fail to write to Google Calendar.
• The preserve path strips all VALARMs when the user edits only the event title.

Phase to address: Multiple reminders phase. The dedup key change and schema migration must land in the same plan. Google cap validation must land in the same plan as Google write-back support.

---

Pitfall 7: Drizzle Auto-Migrate on Boot on MariaDB 11 — The Three Failure Modes

What goes wrong: v1.2 adds zero-manual-setup: the API process runs pending migrations automatically at startup. There are three distinct failure modes specific to this stack:

Failure mode A — Journal-hash mismatch with legacy tracking. The __drizzle_migrations table records applied migrations by tag. If any migration file was renamed after it was applied to an existing database (or if the journal was re-generated, changing the when timestamp), drizzle-kit migrate will not find the matching tag in __drizzle_migrations and will try to re-apply the already-applied migration. On MariaDB, re-running ALTER TABLE ... ADD COLUMN for a column that already exists returns Duplicate column name — not a transaction rollback, but a crash. This is the "journal-hash mismatch" lesson from D-MIGRATION-10-01.

Failure mode B — False destructive diff if db:push logic is used. Any code path that calls drizzle-kit push (even programmatically or from a startup script) against the live MariaDB will schedule TRUNCATE/DROP. The drizzle migrate API (programmatic via drizzle-orm/migrator) is safe — it applies committed .sql files and does not introspect the live DB. The failure mode is: a developer adds a startup call that uses the wrong drizzle API entry point.

Failure mode C — Concurrent startup race (two container instances). If the Docker Compose stack is ever restarted in a way that brings up two API containers briefly (e.g., a rolling update or docker-compose up --scale api=2), both instances call migrate() at startup. MariaDB does not have advisory locks by default. Both instances read __drizzle_migrations, both see the same unapplied migrations, and both attempt to apply them simultaneously. The first to commit wins; the second hits Duplicate column name or a primary key conflict and crashes. The container crash loop then restarts the container, which succeeds because migrations are now applied — but the crash log looks like a startup failure.

Why it happens: Startup migration is convenient but runs without a human watching the DDL. The existing dev workflow always runs pnpm db:migrate explicitly, so a developer sees the output. Auto-migrate is invisible unless there is explicit logging. On MariaDB (no DDL transactions), a partially-applied migration leaves the schema in an undefined state.

How to avoid: Use the drizzle-orm/migrator programmatic API (migrate(db, { migrationsFolder: '...' })), not drizzle-kit CLI, in the startup path. The migrator API applies committed SQL files sequentially and tracks via __drizzle_migrations — it is safe for auto-migrate.

Add a startup log that prints each migration file name as it is applied (or "already applied, skipping"). This makes auto-migrate auditable.

For the concurrent-startup race: wrap the migrate call in a MariaDB advisory-lock table: INSERT INTO migration_lock (id) VALUES (1) with a unique constraint. If the insert fails, the other instance already holds the lock and is migrating — wait and retry. On success, run migrations, then DELETE FROM migration_lock WHERE id=1. This is a single-row sentinel table, created before any other migration.

For distinguishing fresh-DB vs existing-DB: the __drizzle_migrations table not existing means a fresh DB — apply all migrations. The table existing with all entries means fully migrated — skip. The table existing with some entries means a partial state — apply only the unapplied subset (normal drizzle behavior). No special-casing needed; the migrator handles this correctly.

Warning signs:

• Duplicate column name error in the API startup log immediately after deployment.
• Two container instances log "applying migration 0003_..." at the same timestamp.
• The API container crashes on first start but succeeds on second start (concurrent-race symptom).
• Any code calling drizzle-kit push in a startup path (grep for it explicitly before shipping).

Phase to address: Zero-manual-setup DB migration phase. The migration_lock sentinel table and the startup log must be in the acceptance criteria. Write a test that runs migrate() twice on the same DB and asserts no error and no duplicate column.

---

Pitfall 8: PWA Dark Mode — Flash of Wrong Theme and Service Worker Cache Staling

What goes wrong: The standard dark mode pattern — read prefers-color-scheme or a localStorage preference and apply a data-theme attribute on <html> — has a flash-of-wrong-theme (FOWT) on initial load if the attribute is set by React (after hydration) rather than by an inline script before the first paint. The user sees light mode for ~100ms then switches to dark. On iOS standalone PWA, this flash is especially visible because the splash screen (controlled by theme-color meta tag) may not match the applied theme.

The deeper issue: Schedule-X uses --sx-color-* CSS custom properties for its calendar component theming. These are not in the tokens.css semantic token layer established in Phase 17. If dark mode only updates the FamilySync token variables and not the --sx-color-* variables, the calendar component remains in light mode regardless of the document theme — a visually broken state that is easy to miss in desktop testing (because developers often test on a light system preference).

A service worker cache complication: the Workbox-managed precache caches index.html and all static assets at build time. If the theme preference is baked into a cached index.html (e.g., via a server-side render or a build-time default), the cached version will always load with the light-mode default, overriding the user's stored preference. In Vite PWA (client-side rendered), this is not the primary risk — but if the service worker caches a CSS file that includes hardcoded light-mode colors (not variables), dark mode changes deployed in a new build will not reach the user until the service worker updates.

Why it happens: Dark mode is treated as a CSS-only concern but the FOWT is a JS execution timing concern. Schedule-X's custom properties are undocumented relative to external theming. Service worker cache invalidation for CSS changes requires a cache-busting strategy.

How to avoid: Prevent FOWT: inject a minimal inline <script> in index.html (before any CSS) that reads localStorage.getItem('theme') and sets document.documentElement.dataset.theme synchronously. This runs before any CSS is parsed, preventing the flash. The React app then reads the same localStorage key on mount to initialize the Zustand theme store.

Map all --sx-color-* variables used by Schedule-X to the FamilySync dark/light token values. Inspect the Schedule-X @schedule-x/theme-default CSS to enumerate all --sx-* variables and override them in a tokens.css [data-theme="dark"] block. Assert that the calendar renders in dark mode during the dark mode acceptance test.

For service worker cache: vite-plugin-pwa handles cache busting via file hashing in the build output. Verify that tokens.css (or whichever file holds the dark mode variables) is included in the Workbox precache manifest — if it is in the public directory without a hash, it may not be cache-busted on deploy. Move all theme CSS into a hashed build output file.

For iOS standalone PWA theme-color: update the <meta name="theme-color"> dynamically using document.querySelector('meta[name="theme-color"]').setAttribute('content', ...) when the theme toggles. iOS reads theme-color for the status bar color. A static theme-color will not match the active dark theme.

Warning signs:

• Brief white flash visible on page load when dark mode is selected.
• The calendar component (Schedule-X) shows light colors while the rest of the app is dark.
• iOS status bar color does not match the active theme.
• Deploying a dark mode CSS update does not reach users until they manually clear the service worker cache.

Phase to address: PWA dark mode phase. The FOWT fix (inline script in index.html) and Schedule-X variable mapping must be in the acceptance criteria. Test on both light and dark system preferences. Test with the service worker active (not disabled).

---

Pitfall 9: OAuth Callback Through Pangolin/Newt Tunnel — Redirect URI Mismatch and State Cookie Collision

What goes wrong: The Google OAuth flow requires registering exact redirect URIs in the Google Cloud Console. The Pangolin/Newt tunnel exposes the app at a public hostname (e.g., familysync.example.com). The registered redirect URI must match exactly: https://familysync.example.com/api/auth/google/callback. If the redirect URI in the Google Cloud Console is http:// instead of https://, or includes/omits a trailing slash, or uses the internal hostname instead of the Pangolin hostname, the callback returns redirect_uri_mismatch from Google.

A second issue: the existing Authelia OIDC flow already uses an OAuth state cookie (oidc.state) managed by @hono/oidc-auth (stored as a cookie on the domain). The Google OAuth flow also requires a state parameter to prevent CSRF. If both flows use the same cookie name, or if the @hono/oidc-auth middleware intercepts the Google OAuth callback URL (because it pattern-matches /api/* for auth), the Google callback's code parameter is consumed by the Authelia handler before the Google handler sees it — resulting in a state mismatch or invalid_grant error.

A third issue: the Pangolin/Newt tunnel may terminate TLS and forward HTTP internally. If the API receives the Google callback over HTTP (forwarded internally), but the redirect_uri registered in Google is https://, Google's OAuth server rejects the authorization code exchange with redirect_uri_mismatch because the redirect_uri in the token exchange request is constructed from the internal HTTP URL, not the external HTTPS URL.

Why it happens: Two OAuth flows in one app (Authelia OIDC for user login + Google OAuth for calendar access) use overlapping mechanisms (cookies, state params, callback routes). The Pangolin/Newt HTTPS termination creates an HTTP-internally-but-HTTPS-externally environment where naive URL construction picks the wrong scheme.

How to avoid: Mount the Google OAuth callback at a distinct path that the Authelia @hono/oidc-auth middleware does not intercept: /api/providers/google/callback (not under /api/auth/). Apply the Authelia OIDC middleware only to routes that need a logged-in session, not as a global catch-all for /api/*. The Google callback handler does not need an Authelia session — it needs the Google state param. Apply authentication to the Google OAuth initiation endpoint (user must be logged in to connect Google), but not to the callback endpoint (callback must be reachable without a session because Google redirects there).

Use distinct state cookie names: the Authelia flow uses oidc.state (managed by @hono/oidc-auth); the Google flow should use google.oauth.state (managed by the Google OAuth handler). Store the state in a HttpOnly; SameSite=Lax; Secure cookie with a 10-minute TTL.

For the HTTPS scheme: read the external hostname from a EXTERNAL_BASE_URL environment variable (e.g., https://familysync.example.com) and construct all OAuth redirect URIs from it. Never derive the redirect URI from req.headers.host or req.protocol — the internal forwarded values will be wrong. Add EXTERNAL_BASE_URL to the required env checklist in the zero-setup wizard.

Register the redirect URI in Google Cloud Console as exactly ${EXTERNAL_BASE_URL}/api/providers/google/callback.

Warning signs:

• Google OAuth callback returns redirect_uri_mismatch.
• After completing the Google consent screen, the app returns to the homepage without connecting the account (silent failure).
• Authelia OIDC errors appear in logs during a Google OAuth flow (state cookie collision).
• The Google callback URL in server logs shows http:// instead of https://.

Phase to address: Self-service Google OAuth onboarding phase. The EXTERNAL_BASE_URL env var and the distinct callback path must be established before any OAuth flow is implemented. Test the full flow end-to-end over the Pangolin tunnel (not just localhost) as the acceptance gate.

---

Pitfall 10: Google OAuth Token Storage — Encryption Key Reuse and Scope Creep

What goes wrong: The Google OAuth access token (short-lived, ~1 hour) and refresh token (long-lived) must be stored securely. The existing member_credentials table stores the Fastmail app password encrypted with APP_PASSWORD_ENCRYPTION_KEY (AES-256-GCM). The tempting approach: store the Google refresh token in the same member_credentials table with the same encryption key, adding a google_refresh_token column.

The first issue: provider_type is already UNIQUE(user_id) on member_credentials (enforced by uniq_member_credential_user). A member with both a Fastmail credential and a Google credential would need two rows but the unique constraint allows only one per user. Attempting to upsert the Google credential overwrites the Fastmail credential, breaking CalDAV.

The second issue: the Google access token should not be stored persistently — it expires in 1 hour and must be refreshed on use. If the code stores the access token as well as the refresh token, the stored access token will always be stale and the code must always call the token refresh endpoint anyway. Storing the access token wastes a column and tempts future code to use it without checking expiry.

The third issue: the Google OAuth scope should be the minimum needed. If the developer uses https://www.googleapis.com/auth/calendar (full calendar access) instead of the split calendar.readonly + calendar.events scopes, Google requires manual verification review for production status. Use the minimum scope needed.

Why it happens: The member_credentials unique constraint and the provider_type discriminator were designed for a single provider per user. Multi-provider support requires rethinking the credential storage schema.

How to avoid: Change the member_credentials schema for v1.2: drop the UNIQUE(user_id) constraint and replace it with UNIQUE(user_id, provider_type). This allows one row per provider per user. The migration is additive (drop unique, add composite unique). Verify with drizzle-kit generate that the generated SQL is DROP INDEX uniq_member_credential_user; ADD UNIQUE KEY uniq_member_credential_user_provider (user_id, provider_type) — additive DDL plus an index drop. The index drop is safe on MariaDB (not a TRUNCATE).

Store only the Google refresh token (not the access token). Add a google_refresh_token_encrypted column (or a generic oauth_refresh_token_encrypted column) to the Google provider_type row. Derive fresh access tokens at request time using the refresh token — cache the access token in memory (not in the DB) with its expiry time.

Use scopes: https://www.googleapis.com/auth/calendar.readonly + https://www.googleapis.com/auth/calendar.events. Request them space-separated. Store the granted scopes alongside the refresh token so the app knows what the user consented to.

Warning signs:

• An attempt to add a second member_credentials row for the same user hits a unique constraint violation.
• member_credentials for a user shows provider_type: 'google' but the CalDAV credential is gone.
• The access token column in the DB is always expired.
• Google authorization flow requests the https://www.googleapis.com/auth/calendar scope (full access, not split).

Phase to address: Provider abstraction phase (schema migration plan) and Google OAuth onboarding phase. The schema change to UNIQUE(user_id, provider_type) must land before any Google credential storage code is written.

---

Pitfall 11: Dependency Updates — ESLint 10 Pin and Breaking Change Cascade

What goes wrong: The CI dependency audit (Phase 16) surfaces outdated packages. Bulk-applying pnpm up or pnpm audit fix will attempt to update ESLint to v10, which breaks eslint-plugin-react and eslint-plugin-react-hooks (both declare only eslint@9.x as a peer dependency as of 2026-06). When ESLint 10 is installed, both plugins either throw EBADPEERCONN at install time or emit no errors at lint time (silently disabled), breaking the CI lint gate.

A secondary risk: @schedule-x/calendar and @schedule-x/theme-default have been updated (currently pinned at 4.6.0 in apps/pwa). Schedule-X 5.x (if released) changes the --sx-color-* variable naming. If the dependency update phase bumps Schedule-X to a major version before the dark mode phase, the dark mode variable mapping work must be redone with the new variable names.

A third risk: drizzle-kit and drizzle-orm minor versions must be updated together. The drizzle-orm/mysql2 import path and the drizzle-orm/migrator API are version-coupled. If drizzle-orm is bumped to 0.46.x but drizzle-kit stays at 0.31.x, the snapshot format version mismatch may cause generate to produce an incompatible snapshot that migrate cannot parse.

Why it happens: pnpm up or pnpm audit --fix applies updates greedily across the dependency tree without respecting known breaking-change boundaries. The project already knows about the ESLint 9.x pin but a future developer (or an automated tool) may not.

How to avoid: Update dependencies manually, one package or one ecosystem at a time, with the CI lint gate running after each batch. Never use pnpm up --latest or pnpm audit --fix without reviewing the changeset.

ESLint: hold at 9.x until eslint-plugin-react and eslint-plugin-react-hooks both publish ESLint 10 peerDep support and the release notes confirm compatibility. Add a comment in the root package.json above the "eslint" entry: // pinned at 9.x — eslint-plugin-react does not support eslint@10 yet.

Schedule-X: update minor versions only (4.x → 4.y). Hold at major 4 until dark mode theming is complete and the variable mapping is locked. Check Schedule-X release notes for --sx-color-* variable changes before any minor update.

Drizzle: always update drizzle-orm and drizzle-kit in the same commit. After updating, run pnpm db:generate in a dry-run (the output must be "No schema changes, nothing to migrate") to verify the snapshot format compatibility.

Warning signs:

• ESLint exits 0 (no errors reported) but previously failing lint rules now pass — plugin silently disabled.
• eslint-plugin-react@X requires eslint@">=9.0.0 <10.0.0" but got eslint@10.x.x in pnpm install output.
• drizzle-kit generate emits a snapshot with a different version field than the existing snapshots in meta/.
• Schedule-X calendar renders with missing styles after a version bump.

Phase to address: CI dependency update phase (last in milestone, after all feature phases). Treat each package ecosystem as a separate update batch. Run the full CI suite after each batch.

---

Technical Debt Patterns

Shortcut	Immediate Benefit	Long-term Cost	When Acceptable
Keeping UNIQUE(user_id) on member_credentials for the Google credential	No schema migration needed	Can only store one provider per user; Google credential overwrites Fastmail credential	Never — change to UNIQUE(user_id, provider_type) before any Google credential storage
Storing Google access tokens persistently in the DB	Avoids token refresh logic	Access tokens expire in 1 hour; all stored values are always stale	Never — cache in memory only; persist only the refresh token
Using singleEvents: true for Google Calendar event fetch	Simpler API call	Cannot reconstruct RRULE; recurring events appear as individual orphan events	Never — use singleEvents: false for the FamilySync data model
Skipping the migration_lock sentinel table for auto-migrate	One fewer migration table	Concurrent startup races cause Duplicate column name crash loop	Never for a production deployment; acceptable in single-instance local dev
Dark mode applied via React state (after hydration)	Simpler code	Flash-of-wrong-theme on every cold load	Never — use inline <script> in index.html to set the theme synchronously
Deriving OAuth redirect URI from req.headers.host	No env var to configure	Returns internal hostname through Pangolin tunnel; causes redirect_uri_mismatch	Never — read from EXTERNAL_BASE_URL env var
Bumping ESLint to v10 with other dependencies	Fewer outdated warnings	eslint-plugin-react is disabled silently; lint gate appears green but catches nothing	Never until eslint-plugin-react publishes v10 support
Not handling Google 410 Gone (expired syncToken)	Simpler sync code	All incremental sync halts permanently after 7 days of inactivity	Never — 410 is a documented, expected Google API response

---

Integration Gotchas

Integration	Common Mistake	Correct Approach
Google Calendar API	singleEvents: true in events.list	Use singleEvents: false; fetch modified instances separately
Google Calendar API	Not handling status: "cancelled" instances	Map cancelled instances to EXDATE on the master RRULE
Google Calendar API	Ignoring 410 Gone on syncToken expiry	Catch 410, clear token, enqueue full re-sync
Google Calendar API	Using https://www.googleapis.com/auth/calendar scope	Use calendar.readonly + calendar.events (non-restricted, no Google verification required)
Google OAuth	Constructing redirect URI from req.protocol/req.hostname	Read from EXTERNAL_BASE_URL env var; Pangolin terminates TLS so internal protocol is HTTP
Google OAuth	Sharing state cookie name with @hono/oidc-auth Authelia flow	Use google.oauth.state cookie; mount Google callback outside the Authelia middleware scope
Google refresh token	Storing access tokens in DB	Cache access tokens in memory with expiry; persist only refresh token (encrypted)
Drizzle auto-migrate	Calling drizzle-kit push programmatically at startup	Use drizzle-orm/migrator migrate() API — applies committed SQL files, never introspects live DB
Drizzle auto-migrate	No concurrent-startup protection	Implement migration_lock sentinel row with INSERT ... ON DUPLICATE KEY IGNORE
member_credentials schema	UNIQUE(user_id) blocks multi-provider	Migrate to UNIQUE(user_id, provider_type) before writing Google credential code
Schedule-X dark mode	Not overriding --sx-color-* variables in dark token block	Enumerate all --sx-* variables from @schedule-x/theme-default CSS and map them
PWA dark mode	Setting data-theme in React (after hydration)	Inline <script> in index.html before CSS to set data-theme synchronously on load
Vite PWA service worker	tokens.css in public/ without hash	Move theme CSS into hashed build output; verify Workbox precache manifest includes it

---

Performance Traps

Trap	Symptoms	Prevention	When It Breaks
Google events.list with no timeMin/timeMax	Fetches all events in history; response > 5MB; rate limit hit	Always pass a bounded time window (e.g., 6 months past, 1 year future)	First sync for a calendar with >1000 events
Google instances fetch per recurring master event	N+1 API calls for N recurring events	Batch: fetch all instances in the time window in one call; merge by master event ID	Calendars with 10+ recurring series
MariaDB auto-migrate running complex migrations on startup	Long startup delays; health check fails before migration completes	Log migration progress; set Docker healthcheck start_period long enough	Migrations with ALTER TABLE on a table with >50K rows
Multiple VALARMs in scheduler SQL query without index	Full calendar_events scan on every scheduler tick	Index on reminder_lead_minutes column (or event_reminders.lead_minutes if junction table)	Tables with >10K events

---

Security Mistakes

Mistake	Risk	Prevention
Google refresh token stored unencrypted	Stolen DB backup exposes ability to read all of a member's Google Calendar indefinitely	Encrypt with APP_PASSWORD_ENCRYPTION_KEY (AES-256-GCM) same as Fastmail app passwords
Google OAuth state param not validated on callback	CSRF: attacker can link their Google account to the victim's FamilySync session	Validate state against the google.oauth.state cookie; reject mismatches with 400
Google callback endpoint accessible without session check on initiation	Any unauthenticated caller can initiate a Google OAuth flow for any user	Require authenticated FamilySync session to initiate the flow (/api/providers/google/connect); the callback itself needs no session but must validate the state cookie
Google scopes stored but not verified on callback	User may grant narrower scopes than requested; write-back fails silently	Check scope in the token response; if write scope is absent, mark the provider as read-only and surface in UI
EXTERNAL_BASE_URL exposed in a public API response	Discloses internal routing; low severity but unnecessary	Keep env vars server-side only; never return infrastructure config in API responses
Migration lock table not cleaned up on crash	Next startup finds a stale lock and never migrates	Set a locked_at timestamp in the lock row; auto-release locks older than 60 seconds

---

UX Pitfalls

Pitfall	User Impact	Better Approach
Dark mode toggle has no system-follow option	Wife on iPhone expects dark mode to follow iOS system preference automatically	Implement three options: Light / Dark / System (default); System reads prefers-color-scheme media query and updates on system change
Google "Connect" button initiates OAuth without explaining what access is granted	Non-technical wife confused by Google consent screen listing calendar permissions	Show a one-sentence explanation before the OAuth redirect: "FamilySync will read and update your Google Calendar events."
Google auth failure surfaces a raw error message	invalid_grant or redirect_uri_mismatch visible to end user	Map known Google OAuth error codes to friendly messages; provide a "Try again" button that re-initiates the flow
Multiple reminders UI with no order or visual grouping	Hard to tell which reminder fires when	Show reminders sorted by lead time (earliest first); each entry shows the computed fire time ("4 days before, at 9:00 AM")
Dark mode flash on cold PWA load	Wife on iPhone sees white flash on dark mode	Inline script in index.html sets theme before first paint; no React wait required
Zero-setup wizard asks for Google OAuth credentials before explaining the App Flow	Non-technical user confused by "Client ID" and "Client Secret" terms	Name the fields plainly; link to the FamilySync deployment guide step that shows where to find them in the Google Cloud Console

---

"Looks Done But Isn't" Checklist

• Google OAuth flow: Refresh token stored — but 410 syncToken expiry handler missing. Verify with a forced syncToken reset (delete the stored token, check that the next poll triggers a full re-sync without crashing).
• Google recurrence: Master event fetched with singleEvents: false — but modified/canceled instances not fetched. Verify by canceling one occurrence in Google Calendar and confirming it does not appear in FamilySync.
• Provider abstraction: Interface defined — but the Fastmail outbox worker's isDraining guard and drainRequested flag behavior is unchanged. Verify with the existing outbox integration tests against the new interface.
• Multiple reminders: Multiple VALARM objects in rawVevent — but scheduler dedup key still uid:dtstartMs (not uid:dtstartMs:leadMinutes). Verify by creating an event with two reminders and confirming two separate pushes fire at the correct times.
• Auto-migrate on boot: Migrations run at startup — but no concurrent-startup protection. Verify by starting two container instances simultaneously and confirming exactly one migration run, no crash loop.
• Dark mode: data-theme applied — but Schedule-X --sx-color-* variables not overridden. Verify by switching to dark mode and checking the calendar view specifically (not just the nav/lists).
• Google OAuth through Pangolin: OAuth flow works on localhost — but redirect URI uses internal hostname. Verify by completing the Google OAuth flow over the Pangolin public URL (EXTERNAL_BASE_URL), not via localhost:3000.
• Dependency updates: ESLint updated — but eslint-plugin-react compatibility not verified. Verify by introducing a deliberate React lint violation and confirming the CI lint gate catches it after the update.
• Google token expiry: Access tokens cached in memory — but expiry check missing. Verify that a request made >1 hour after the last token fetch triggers a silent refresh, not a 401 from Google.

---

Recovery Strategies

Pitfall	Recovery Cost	Recovery Steps
Google refresh token 7-day expiry in Testing status	LOW	Promote app to Production status in Google Cloud Console; member re-authorizes once
Drizzle auto-migrate Duplicate column name crash	MEDIUM	Manually mark the migration as applied in __drizzle_migrations; restart container
Concurrent migration lock stuck (crash before lock release)	LOW	DELETE FROM migration_lock WHERE id=1 in the DB; restart container
Google syncToken 410 — incremental sync stopped	LOW	Delete stored syncToken from member_credentials; next poll performs full re-sync
member_credentials unique constraint violation (Google overwrites Fastmail)	HIGH	Restore from DB backup; apply the UNIQUE(user_id, provider_type) migration immediately
OAuth redirect URI mismatch (Pangolin hostname not registered)	LOW	Add the correct HTTPS URL to Google Cloud Console Authorized Redirect URIs; no code change
Dark mode flash in production (inline script missing)	LOW	Add inline <script> to index.html; rebuild and deploy; service worker cache busted by new hash
ESLint 10 upgrade breaks plugin — lint gate silently passes	MEDIUM	Roll back ESLint to 9.x in root package.json; re-run CI to confirm lint gate fails again on known violations

---

Pitfall-to-Phase Mapping

Pitfall	Prevention Phase	Verification
Google refresh token 7-day expiry (Testing vs Production status)	Google Calendar provider (phase start)	Document and enforce before any token storage code ships
Google recurrence model mismatch (singleEvents, EXDATE)	Google Calendar provider (recurrence plan)	Unit test: mock Google API response → assert reconstructed VCALENDAR passes ical.js + RecurExpansion
Google syncToken 410 handling	Google Calendar provider (sync/poller plan)	Integration test: simulate 410 → assert full re-sync triggered, no crash
Google all-day timezone / useDefault reminder	Google Calendar provider (normalization plan)	Unit test: UTC normalization of start.dateTime with offset; useDefault: true maps to null
Provider abstraction Fastmail regression	Provider abstraction phase (must ship first)	All existing outbox/poller/scheduler tests pass unchanged against the new interface
Multiple VALARM dedup key and Google 5-cap	Multiple reminders phase	Integration test: event with 2 reminders fires 2 pushes; Google write-back with 6 reminders returns validation error before write
Drizzle auto-migrate: journal mismatch, concurrent race, false destructive diff	Zero-setup DB migration phase	Test: run migrate() twice on same DB → no error; start two containers simultaneously → one applies, one waits
PWA dark mode FOWT and Schedule-X coverage	PWA dark mode phase	Playwright test: toggle dark mode, assert --sx-color-* computed values on the calendar element match dark theme
OAuth callback through Pangolin redirect URI	Self-service Google OAuth onboarding phase	End-to-end test over Pangolin tunnel hostname (not localhost)
Google token encryption and multi-provider schema	Provider abstraction phase (schema migration)	UNIQUE(user_id, provider_type) in place; integration test: add Fastmail + Google credentials for same user → both rows present
ESLint 10 breaking change in dependency updates	CI dependency update phase (last in milestone)	Update ESLint separately; verify lint gate still catches a known violation after update

---

Sources

• Project source: apps/api/src/broker/reminderScheduler.ts, vevent.ts, outboxWorker.ts, client.ts (inspected directly)
• Migration history: apps/api/src/db/migrations/meta/_journal.json, migration SQL files (inspected directly)
• .planning/RETROSPECTIVE.md — v1.0 and v1.1 lessons (journal-hash mismatch, false destructive diff, node-cron silent skip, runner-probe-first)
• .planning/quick/260610-cr8-adopt-drizzle-generate-migrate-workflow-/260610-cr8-PLAN.md — Drizzle MariaDB push foot-gun (direct source)
• .planning/todos/completed/adopt-drizzle-migrations-workflow.md — false destructive diff root cause (direct source)
• .planning/milestones/v1.1-phases/10-admin-role-settings/10-01-PLAN.md — migration workflow and UNIQUE(user_id) constraint history (direct source)
• .planning/milestones/v1.1-phases/11-per-event-reminders/11-RESEARCH.md — VALARM classification, scheduler dedup key design (direct source)
• CLAUDE.md — ESLint 9.39.4 pin rationale, stack constraints, Schedule-X version, CI runner constraints (direct source)
• PROJECT.md — Key decisions D-10 through D-20, constraint table, v1.2 feature list (direct source)
• Google Calendar API documentation knowledge (refresh token expiry policy, singleEvents parameter, 410 Gone syncToken expiry, reminders.useDefault, scope tiers) — HIGH confidence from repeated confirmed behavior
• OAuth2 PKCE / state cookie mechanics — HIGH confidence from shipped Authelia OIDC implementation in this codebase
• Drizzle ORM programmatic migrator API (drizzle-orm/migrator) — MEDIUM confidence (verify against drizzle-orm release notes for the installed version before shipping auto-migrate)

---

Pitfalls research for: FamilySync v1.2 Multi-Provider, Theming & Zero-Setup Researched: 2026-06-19